Attempt to fix Pyright environments/exclude. Fix some low-hanging fru…

…it docstring lints.

doc/development/support-code.md

@@ -26,10 +26,7 @@ a [workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html)!
 
 ## Verilog Generator
 
-```{eval-rst}
-.. automodule:: sentinel.gen
-    :members:
-```
+See {py:mod}`sentinel.gen`.
 
 ## Examples
 

doc/usage/reference.md

@@ -67,7 +67,16 @@ for a full working example.
 
 ## Public API
 
+```{eval-rst}
+.. automodule:: sentinel
+```
+
 ```{eval-rst}
 .. automodule:: sentinel.top
     :members:
 ```
+
+```{eval-rst}
+.. automodule:: sentinel.gen
+    :members:
+```

pyproject.toml

@@ -59,6 +59,20 @@ pycodestyle.max-line-length = 79  # flake8 compat
 # sys.path modified, nothing we can do about this right now.
 "tests/riscof/sentinel/riscof_sentinel.py" = ["E402"]
 
+[tool.pyright]
+# Not our code.
+# FIXME: Doesn't seem to stop Pylance from reporting issues on these files
+# when open in VSCode editor? Keep it
+exclude = [
+    # These three are defaults.
+    "**/node_modules",
+    "**/__pycache__",
+    "**/.*",
+    "tests/formal/riscv-formal/**",
+    "tests/upstream/riscv-tests/**" ,
+    "tests/riscof/sail_cSim/**"
+]
+
 # Lots of false-positives due to Pyright not knowing about Amaranth.
 [[tool.pyright.executionEnvironments]]
 root = "examples/attosoc.py"
@@ -74,6 +88,7 @@ reportAttributeAccessIssue = false
 reportOptionalMemberAccess = false
 reportGeneralTypeIssues = false
 reportOperatorIssue = false
+reportInvalidTypeForm = false
 
 [[tool.pyright.executionEnvironments]]
 root = "tests/formal"

src/sentinel/__init__.py

@@ -0,0 +1,13 @@
+"""The Sentinel RISC-V CPU Package.
+
+There is no ``__all__``; star imports are not presently supported. Users will
+likely want to import or run one of the following modules directly:
+
+.. testcode::
+
+    from sentinel.top import Top
+
+::
+
+    python -m sentinel.gen --help
+"""

src/sentinel/align.py

@@ -20,7 +20,7 @@ def __init__(self):
         }
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         # DataPath.dat_w constantly has traffic. We only want to latch
@@ -66,7 +66,7 @@ def __init__(self):
         }
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         selected_dat = Signal.like(self.wb_dat_r)
@@ -112,7 +112,7 @@ def __init__(self):
         }
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         # TODO: Misaligned accesses

src/sentinel/alu.py

@@ -19,7 +19,7 @@ def __init__(self):
         }
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         with m.If(self.latch):
@@ -64,7 +64,7 @@ def __init__(self):
         self.rdata_align = ReadDataAlign()
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         m.submodules.rdata_align = self.rdata_align
@@ -105,7 +105,7 @@ def __init__(self, width, op):
         self.o = Signal(width)
         self.op = op
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
         m.d.comb += self.o.eq(self.op(self.a, self.b))
         return m

src/sentinel/control.py

@@ -41,7 +41,7 @@ def __init__(self):
 
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         insn = Insn(self.insn)
@@ -87,7 +87,8 @@ def elaborate(self, platform):
                 with m.Case(OpcodeType.JALR):
                     m.d.sync += self.requested_op.eq(0x98)
                 with m.Case(OpcodeType.BRANCH):
-                    m.d.sync += self.requested_op.eq(Cat(insn.funct3, C(0x88 >> 3)))
+                    m.d.sync += self.requested_op.eq(Cat(insn.funct3,
+                                                         C(0x88 >> 3)))
                 with m.Case(OpcodeType.LOAD):
                     op_map = Cat(insn.funct3, C(0x08 >> 3))
                     m.d.sync += self.requested_op.eq(op_map)
@@ -217,7 +218,7 @@ def __init__(self, ucode: Optional[TextIO] = None):
             "csr": Out(CSRControlSignature)
         })
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         m.submodules.ucoderom = self.ucoderom
@@ -305,7 +306,7 @@ def __init__(self, ucoderom):
         # next_adr.
         self.test = Signal()
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         m.d.sync += self.next_adr.eq(self.adr + 1)

src/sentinel/datapath.py

@@ -71,7 +71,7 @@ class ProgramCounter(Component):
     def __init__(self):
         super().__init__(PcSignature.flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         with m.Switch(self.ctrl.action):
@@ -104,7 +104,7 @@ def __init__(self, *, formal):
 
         super().__init__()
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
         m.submodules.mem = self.mem
 
@@ -154,7 +154,7 @@ class CSRFile(Component):
     MCAUSE = 0xA
     MIP = 0xC
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         mstatus = Signal(MStatus, init={"mpp": 0b11})
@@ -271,7 +271,7 @@ def __init__(self):
         }
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         with m.Switch(self.reg_r_sel):
@@ -314,7 +314,7 @@ def __init__(self, *, formal=False):
         self.regfile = RegFile(formal=formal)
         self.csrfile = CSRFile()
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         m.submodules.pc_mod = self.pc_mod

src/sentinel/decode.py

@@ -60,7 +60,7 @@ def __init__(self):
         self._rom_init()
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         # FIXME: Use _CSR somehow to make self.addr slicing nicer?
@@ -111,7 +111,7 @@ def __init__(self):
 
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         insn = Insn(self.insn)
@@ -150,7 +150,7 @@ def __init__(self):
 
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         insn = Insn(self.insn)
@@ -181,15 +181,17 @@ def elaborate(self, platform):
                             with m.If(insn.funct7 != 0):
                                 m.d.sync += self.exception.valid.eq(1)
                         with m.Else():
-                            with m.If((insn.funct7 != 0) & (insn.funct7 != 0b0100000)):
+                            with m.If((insn.funct7 != 0) &
+                                      (insn.funct7 != 0b0100000)):
                                 m.d.sync += self.exception.valid.eq(1)
                 with m.Case(OpcodeType.LUI):
                     pass
                 with m.Case(OpcodeType.AUIPC):
                     pass
                 with m.Case(OpcodeType.OP):
                     with m.If((insn.funct3 == 0) | (insn.funct3 == 5)):
-                        with m.If((insn.funct7 != 0) & (insn.funct7 != 0b0100000)):  # noqa: E501
+                        with m.If((insn.funct7 != 0) &
+                                  (insn.funct7 != 0b0100000)):
                             m.d.sync += self.exception.valid.eq(1)
                     with m.Else():
                         with m.If(insn.funct7 != 0):
@@ -203,7 +205,8 @@ def elaborate(self, platform):
                     with m.If((insn.funct3 == 2) | (insn.funct3 == 3)):
                         m.d.sync += self.exception.valid.eq(1)
                 with m.Case(OpcodeType.LOAD):
-                    with m.If((insn.funct3 == 3) | (insn.funct3 == 6) | (insn.funct3 == 7)):
+                    with m.If((insn.funct3 == 3) | (insn.funct3 == 6) |
+                              (insn.funct3 == 7)):
                         m.d.sync += self.exception.valid.eq(1)
                 with m.Case(OpcodeType.STORE):
                     with m.If(insn.funct3 >= 3):
@@ -314,7 +317,7 @@ def __init__(self, *, formal=False):
 
         super().__init__(Signature(sig).flip())
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         m.submodules.csr_attr = self.csr_attr

src/sentinel/exception.py

@@ -31,7 +31,7 @@ class ExceptionRouter(Component):
     src: In(SrcSignature)
     out: Out(OutSignature)
 
-    def elaborate(self, platform):
+    def elaborate(self, platform):  # noqa: D102
         m = Module()
 
         exception = Signal(1)

src/sentinel/formal.py

@@ -75,7 +75,7 @@ def __init__(self):
         super().__init__(sig)
         self.cpu = Top(formal=True)
 
-    def elaborate(self, plat):
+    def elaborate(self, plat):  # noqa: D102
         m = Module()
 
         m.submodules.cpu = self.cpu

src/sentinel/gen.py

@@ -1,3 +1,16 @@
+"""Verilog generation module/script for Sentinel.
+
+At present, only running this module directly from the command-line
+(as ``__main__``) is supported:
+
+::
+
+    python -m sentinel.gen --help
+
+Individual functions are documented for completeness and should not be treated
+as public (see :doc:`/development/guidelines`).
+"""
+
 import argparse
 import sys
 from contextlib import contextmanager

src/sentinel/top.py

@@ -1,3 +1,5 @@
+"""Top-Level Module for Amaranth Components of Sentinel CPU."""
+
 from amaranth import Signal, Module
 from amaranth.lib.wiring import Component, Signature, Out, In, connect, flipped
 from amaranth_soc import wishbone

tests/sim/test_top.py

@@ -545,7 +545,7 @@ def control(self):
     def elaborate(self, plat):
         m = Module()
 
-        m.submodules.top = ResetInserter(self.rst)(EnableInserter(self.en)(self.top))
+        m.submodules.top = ResetInserter(self.rst)(EnableInserter(self.en)(self.top))  # noqa: E501
 
         connect(m, flipped(self), self.top)