pyproject.toml

[project]
name = "sentinel"
description = "Embedded RISC-V implementation written in Amaranth"
authors = [
    {name = "William D. Jones", email = "thor0505@comcast.net"},
]
dependencies = [
    "m5meta>=1.0.4",
    "m5pre>=1.0.3",
    "amaranth>=0.5.4",
    "amaranth-soc @ git+https://github.com/amaranth-lang/amaranth-soc",
]
requires-python = ">=3.11"
readme = "README.md"
license = {text = "BSD-2-Clause"}
dynamic = ["version"]

[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

[tool.pytest.ini_options]
pythonpath = [
  "src/",
]
markers = [
  "clks: tuple of clocks to register for simulator.",
  "module: top-level module to simulate.",
  "soc: run SoC simulations."
]
addopts="--ignore=tests/upstream/binaries"
required_plugins = "pytest-amaranth-sim"
long_vcd_filenames = true
extend_vcd_time = "41666666"  # extend by half a 12MHz period.

[tool.ruff]
src = [ "src", "tests" ]  # https://docs.astral.sh/ruff/faq/#how-does-ruff-determine-which-of-my-imports-are-first-party-third-party-etc
line-length = 79  # flake8 compat
# External code- submodules or auto-generated.
extend-exclude = [ 
    "tests/formal/riscv-formal/**",
    "tests/upstream/riscv-tests/**" ,
    "tests/riscof/sail_cSim/**"
]

# Also, accept the risks of preview mode to try the unstable E checks and pydoclint support.
# These will also catch missing docstrings and other nits, which pydoclint doesn't.
[tool.ruff.lint]
preview = true
extend-select = ["E1", "E2", "E3", "RUF100", "E5", "W", "D", "DOC"]
pydocstyle.convention = "numpy"
pycodestyle.max-line-length = 79  # flake8 compat

[tool.ruff.lint.per-file-ignores]
# Short docstrings become CLI help fragments.
"dodo.py" = ["D400", "D403", "DOC201", "DOC402"]
# Tolerate missing strings for tests- they are not a public API.
"tests/**/*.py" = ["D10"]
# 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"
reportInvalidTypeForm = false
reportGeneralTypeIssues = false
reportAttributeAccessIssue = false
reportPossiblyUnboundVariable = false
reportOperatorIssue = false

[[tool.pyright.executionEnvironments]]
root = "src"
reportAttributeAccessIssue = false
reportOptionalMemberAccess = false
reportGeneralTypeIssues = false
reportOperatorIssue = false
reportInvalidTypeForm = false

[[tool.pyright.executionEnvironments]]
root = "tests/formal"
reportArgumentType = false

[[tool.pyright.executionEnvironments]]
root = "tests/riscof/sentinel"
reportIncompatibleMethodOverride = false
reportMissingImports = false  # sys.path modified

[tool.pdm.build]
# src/sentinel/microcode.asm seems to be included already.
includes = [
    "src/sentinel",
]
# Exclude all files in submodules, and non-(raw)-binaries.
excludes = [
    "tests/*/*/.*",
    "tests/*/*/*",
    "tests/upstream/binaries/*.dump",
    "tests/upstream/binaries/*.elf"
]
# README.md and LICENSE.md seem to be included already.
source-includes = [
    ".gitignore",
    "CHANGELOG.md",
    "cliff.toml",
    "examples",
    "sentinel-rt",
    "Cargo.toml",
    "tests",
    "tests/upstream/binaries/*"
]

[tool.pdm.version]
source = "scm"
write_to = "sentinel/version.txt"

[tool.pdm.scripts]
_.env_file = ".env.toolchain"

# Lint
lint = { composite = [
    # Python
    "ruff check {args}",
    # Rust- _clippy includes "cargo check": https://stackoverflow.com/a/57477060
    "cargo clippy --release --examples",
    "cargo doc --release --examples"
], help = "lint Python and Rust sources" }
lint-fix = { composite = [
    # Python
    "ruff check --fix -e",
    # Rust
    "cargo clippy --fix --release --examples --allow-dirty"
], help = "fix automatically-fixable lints" }

# Most Tests
test = { cmd = "pytest", help="run all pytest tests" }
test-quick.cmd = "pytest -k \"test_top or test_upstream or test_witness\""
test-quick.help = "run quick subset of pytest tests"

# Generate
gen = { call = "sentinel.gen:generate", help="generate Sentinel Verilog file" }

# Demo
# PDM "does the right thing" here; specifying "python " interpreter not required:
# https://github.com/pdm-project/pdm/blob/73651b7a948679d31f4d00e8b14c8a51009126e8/src/pdm/cli/commands/run.py#L179
demo = { cmd = "examples/attosoc.py", help="create AttoSoC Sentinel demo bitstream" }
demo-rust = { composite = [
    "cargo build --release --example=attosoc",
    "demo -g target/riscv32i-unknown-none-elf/release/examples/attosoc -b build-rust {args}"
], help = "create AttoSoC Sentinel demo bitstream (Rust version)"}

# Docs
doc = { cmd = "sphinx-build {args} doc/ doc/_build/", help="build documentation" }
doc-test = "sphinx-build -b doctest doc/ doc/_build"
doc-linkck = "sphinx-build doc/ doc/_linkcheck/ -b linkcheck"
doc-auto = "sphinx-autobuild doc/ doc/_build/ --watch src/sentinel --watch examples"

# DoIt wrappers. Prefer using these over running DoIt directly.
doit = { cmd = "doit", help="escape hatch to call doit directly" }
ucode = { cmd = "doit ucode", help="generate supplementary microcode files" }

# YoWASP
use-yowasp = { cmd = "doit prepare_yowasp", help="prepare pdm and tools to use YoWASP binaries" }
use-local.cmd = "doit clean prepare_yowasp"
use-local.help = "revert \"use-yowasp\" changes; use local binaries"

# LUTs
bench-luts = { cmd = "doit bench_luts", help="add stats to LUTs.csv" }
plot-luts = { cmd = "doit plot_luts", help="plot LUTs.csv" }

# Upstream
compile-upstream = { cmd = "doit compile_upstream", help="regnerate riscv-test binaries" }

# RISC-V Formal
rvformal = { cmd = "doit run_sby:{args}", help="run a single RISC-V Formal test" }
# Not clear to me that this is still required after refactors.
rvformal-force = { composite = [
    "doit forget run_sby:{args}",
    "rvformal {args}"
], help="force-run a single RISC-V Formal test"}
rvformal-all = { composite = [
    "doit run_sby:setup",  # serially generate RISC-V Formal files to avoid race condition
    "doit {args:-n 2} run_sby"
], help="run all RISC-V Formal tests" }
rvformal-status.cmd = "doit list_sby_status:{args}"
rvformal-status.help="list a single RISC-V Formal test's status"
rvformal-status-all.cmd = "doit list_sby_status"
rvformal-status-all.help="list all RISC-V Formal tests' status"

# RISCOF
riscof-all = { cmd = "doit run_riscof", help="run all RISCOF tests"}
riscof-override.cmd = "doit run_riscof -t {args}"
riscof-override.help = "run RISCOF with custom testfile"

# Private
_add-ruff.cmd = "pdm add --dev -G lint ruff"
_add-ruff.env = { CARGO_PROFILE_RELEASE_LTO="false" }
_add-ruff.help = "add Ruff linter on MSYS2- work around Rust issue #109797"
_update-ruff.cmd = "pdm update --dev -G lint ruff"
_update-ruff.env = { CARGO_PROFILE_RELEASE_LTO="false" }
_update-ruff.help = "update Ruff linter on MSYS2- work around Rust issue #109797"

# Demo development helpers.
[tool.doit.tasks]
_make_rand_firmware = { platform = "ice40_hx8k_b_evn", interface = "csr"}
_program_rust_firmware = { programmer = "ofl" }

[dependency-groups]
doc = [
    "sphinx>=7.2.6",
    "sphinx-rtd-theme>=2.0.0",
    "myst-parser>=2.0.0",
    "sphinx-autobuild>=2024.2.4",
    "sphinx-prompt>=1.9.0",
]
dev = [
    "amaranth-soc @ git+https://github.com/amaranth-lang/amaranth-soc",
    "bronzebeard>=0.2.1",
    "pytest>=7.4.2",
    "doit>=0.36.0",
    "Verilog-VCD>=1.11",
    "logLUTs @ git+https://github.com/mattvenn/logLUTs@a7fa902a5f70c7d53a654d850f745e36821fbb78",
    "pytest-amaranth-sim>=0.1.0",
]
examples = [
    "amaranth-soc @ git+https://github.com/amaranth-lang/amaranth-soc",
    "bronzebeard>=0.2.1",
    "amaranth-boards @ git+https://github.com/amaranth-lang/amaranth-boards",
    "tabulate>=0.9.0",
    "pyelftools>=0.26",
    "doit>=0.36.0",
]
riscof = [
    "riscof>=1.25.3",
]
remote = [
    "amaranth[remote-build]>=0.5.4",
    "paramiko~=2.7"
]
lint = [
    "ruff>=0.6.7",
]
yowasp = [
    "amaranth[builtin-yosys]>=0.5.4",
    "yowasp-yosys>=0.47.0.0.post805",
    "yowasp-nextpnr-ice40>=0.7.0.0.post519",
]