sentinel TODO List
This page summarizes the documentation that I need to write which hasn’t been yet :).
Todo
This section of guidelines is still in flux. The source code does not necessarily reflect this section’s guidelines.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/guidelines.md, line 33.)
Todo
I can likely relax this restriction without much extra logic (maybe even less logic!), but I haven’t decided what guarantees I’m willing to provide as of 1/10/2025.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/datapath.py:docstring of sentinel_cpu.datapath.CSRFile, line 24.)
Todo
DataPathSrcMux is analogous to
ASrcMux and
BSrcMux for the
ALU. However, I couldn’t get it to optimize
well compared to putting the logic directly in
Top. I keep it around as “dead code” just in
case in comes in handy later. If/when that time comes, I’ll properly
document it.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/datapath.py:docstring of sentinel_cpu.datapath.DataPathSrcMux, line 3.)
Todo
Perhaps include rest of the raw notes on how I derived start locations from opcodes; right now only the results are included.
Start locations need to be documented as constants, including “base” constants where the minor opcode is just added to the base to form the final constant.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/internals.md, line 139.)
Todo
Right now, this isn’t actually private; it is a leaky abstraction
because e.g. an ad-hoc compatible
Layout is created by
sentinel_cpu.control.MappingROM.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/decode.py:docstring of sentinel_cpu.decode.CSRAttributes._DataLayout, line 6.)
Todo
Constants aren’t meaningfully used that much. Get rid of them and convert uses into properties?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/insn.py:docstring of sentinel_cpu.insn.Insn.CSR, line 9.)
Todo
Eventually DecodeException should be defined as a nested
class under Decode, similar to e.g.
ALU.RoutingSignature.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/exception.py:docstring of sentinel_cpu.exception.DecodeException, line 28.)
Todo
I need to create a test that gets latency and throughput for each instruction type of the core.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/internals.md, line 210.)
Todo
A read-only BASE is allowed, but I believe the Rust support code
assumes a writable BASE. I don’t wish to fork riscv-rt
solely for a read-only BASE. So I deal with the potential loss of space
savings for now.
Revisit whether read-only BASE is feasible in the future.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/internals.md, line 320.)
Todo
I need to verify what happens when we RegWrite to the same
address with deasserted read-enable. Will it “blow away” the current
read port value?
(The original entry is located in docstring of sentinel_cpu.ucodefields.RegRead, line 20.)
Todo
Use sphinxcontrib.programoutput
to generate an up-to-date list of commands?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/overview.md, line 69.)
Todo
Decide whether to commit to treat all doit tasks as private/hidden or expose a set
to a user/developer (no leading underscore). Right now, I am not being consistent.
For instance, _build_sail is a command a developer might manually run in rare
cases, but is still currently private b/c of its niche use-case. Where’s the
cutoff for marking private vs public?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/overview.md, line 148.)
Todo
Use sphinxcontrib.programoutput
to generate an up-to-date list of commands?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/overview.md, line 157.)
Todo
As is custom, although public and documented, the
DoIt tasks should be considered unstable; pdm run [any-script-besides-doit]
should be preferred. Any advice to use doit directly on this page is because
“I haven’t made the ergonomics better yet”.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/testing.md, line 3.)
Todo
As mentioned previously,
FormalTop does not connect to the rest of Sentinel via a
well-defined interface.
It relies directly on many sentinel_cpu.top.Top internal signals
that I would rather be exposed via an
Interface, but progress has been slow.
This includes hardcoding microcode addresses constants as class
attributes.
I’m deferring describing how this module works internally until I clean it up. Fortunately, I don’t think it’s not exceptionally difficult to follow in its current state. Cleanup mostly consists of:
Fleshing out the aforementioned interface started in
sentinel_cpu.top.Top.rvfi.Refactoring the implicit state machine from the combination of
in_init,committed_to_insn, andjust_committed_to_insninto an explicit one.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/formal.py:docstring of sentinel_cpu.formal.FormalTop, line 3.)
Todo
Fix goofy formatting, currently (1/11/2025) a
side-effect of how
NORMALIZE_WHITESPACE in doctest works.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/formal.py:docstring of sentinel_cpu.formal.FormalTop, line 66.)
Todo
At present, RISCOF tests presently require Linux to run because I had trouble installing an OCaml toolchain on Windows at the time. In addition, I recall a few *nix-isms in the RISCOF Python package. I will fix this in the future.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/testing.md, line 417.)
Todo
It’d be nice to remove the immediate dependency on make. Since we don’t want
to install the emulators in the system, it should be in principle possible to
cd sail-riscv, do opam install . --deps-only, and then build SAIL manually.
However, I couldn’t get that to work…
Additionally, the default RISCOF SAIL plugin
uses
make, and I haven’t gotten around to ripping that out yet :).
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/development/testing.md, line 539.)
Todo
Can .env.toolchain somehow be used per virtual environment (to allow
per-virtualenv toolchains)?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/usage/installation.md, line 77.)
Todo
I am still working out the details on using Sentinel outside of PDM. There are use cases, such as LiteX, but I’ve decided to wait to implement this until another release.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/usage/installation.md, line 119.)
Todo
demo parameters are only really documented in passing/prose right now, and
not even all of them at that:
Punt the remaining params to development sections?
Prose might be enough?
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/doc/usage/quickstart.md, line 125.)
Todo
Seeing that it’s memory-mapped, there should probably be provisions for a user-supplied Machine Timer.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/top.py:docstring of sentinel_cpu.top.Top, line 43.)
Todo
Right now, the formal harness tends to directly “reach” into
Top
and Components
to read the appropriate signals.
I would prefer encapsulation via an explicity rvfi port
Member, but this process
has been slow.
I will wait to document until this interface Member
is more stable.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/top.py:docstring of sentinel_cpu.top.Top, line 161.)
Todo
Use sphinx-argparse to document arguments automatically.
(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/sentinel-cpu/checkouts/main/src/sentinel_cpu/gen.py:docstring of sentinel_cpu.gen.cli, line 6.)