# User Reference

The [Quickstart](./quickstart.md) is a good reference for how to use Sentinel
from the source repo. These next three sections discuss usage outside of the
source tree.

## Use in Verilog Code

(pre-generated)=
### Pre-Generated Verilog

Each [Codeberg Release](https://codeberg.org/cr1901/sentinel/releases) contains a
standalone generated Verilog file of Sentinel CPU. If you opt to download the
Verilog from releases, **you do not need Python installed to use Sentinel**.
You can automate downloading the Verilog with a script like this:

````{tab} sh
```{substitution-code-block} sh
SENTINEL_VER=sent_latest_tag

wget -O sentinel-v-$SENTINEL_VER.zip https://codeberg.org/cr1901/sentinel/releases/download/$SENTINEL_VER/sentinel-v-$SENTINEL_VER.zip
unzip sentinel-v-$SENTINEL_VER.zip
```
````

````{tab} Powershell
```{substitution-code-block} powershell
set SentinelVer sent_latest_tag

wget -OutFile sentinel-v-$SentinelVer.zip https://codeberg.org/cr1901/sentinel/releases/download/$SentinelVer/sentinel-v-$SentinelVer.zip
Expand-Archive -Path sentinel-v-$SentinelVer.zip -DestinationPath .
```
````

(arbitrary)=
### Verilog From Arbitrary Commits

Generating Verilog of arbitrary commits requires Python >= 3.11, `pdm`, and
`git`.

If you're using Sentinel with `pdm` as your [top-level build system](./installation.md#in-a-pdm-project),
I suggest adding a [pdm script](https://pdm-project.org/latest/usage/scripts/#pdm-scripts)
to provide a shortcut for Verilog generation in your `pyproject.toml`
(_`call = "python -m sentinel_cpu.gen"` does not work!_):

```toml
[tool.pdm.scripts]
gen = { call = "sentinel_cpu.gen:cli", help="generate Sentinel Verilog file" }
```

<!-- The above is equivalent to `pdm run python -m sentinel_cpu.gen`.

Otherwise, you can run:

```
pdm run python -m sentinel_cpu.gen
```

which does the same thing. -->

For all other use cases, I recommend using `pdm` from your top-level build
system, which manages the Sentinel checkout as a `venv` wrapper. Here is a
user-configurable script as an example:

````{tab} sh
```sh
SENTINEL_PATH=./sentinel
SENTINEL_REF=next
SENTINEL_V=sentinel_cpu.v

if ! [ -d $SENTINEL_PATH/.venv ]; then
    git clone https://codeberg.org/cr1901/sentinel_cpu.git $SENTINEL_PATH
    git -C $SENTINEL_PATH checkout $SENTINEL_REF
    pdm install -p $SENTINEL_PATH -G yowasp
fi

pdm run -p $SENTINEL_PATH gen -o $SENTINEL_V
```
````

````{tab} Powershell
```powershell
set SentinelPath ./sentinel
set SentinelRef next
set SentinelV sentinel_cpu.v

if (!(Test-Path $SentinelPath/.venv)){
    git clone https://codeberg.org/cr1901/sentinel_cpu.git $SentinelPath
    git -C $SentinelPath checkout $SentinelRef
    pdm install -p $SentinelPath -G yowasp
}

pdm run -p $SentinelPath gen -o $SentinelV
```
````

<!-- ````{note}
If you can't or don't want to use `pdm`, you need to ensure Sentinel is
[installed](./installation.md#as-a-dependency) as a Python (>= 3.11) package,
preferably in a `venv`. Then, your build system can generate Verilog by
running {mod}`sentinel_cpu.gen` with the correct interpreter:

```
python -m sentinel_cpu.gen
```
```` -->

<!-- Keep in sync with function names above! -->

```{testcode}
:hide:

from sentinel_cpu.gen import cli
```

(am-dep)=
## Use In Amaranth Code

Right now, even from Python, Sentinel consists of rather few tunable knobs.
The only public Sentinel CPU module is the appropriately-named
{py:class}`~sentinel_cpu.top.Top`.

`Top` is an [interface object](https://amaranth-lang.org/rfcs/0002-interfaces.html#interface-definition-library-rfc)
whose {py:class}`~amaranth.lib.wiring.Signature` consists of a [Wishbone](https://cdn.opencores.org/downloads/wbspec_b4.pdf)
Classic bus and an Interrupt ReQuest (IRQ) line. All interface members are
synchronous to the `sync` [clock domain](https://amaranth-lang.org/docs/amaranth/latest/guide.html#control-domains).
Explicit `clk` and `rst` lines are generated for the `sync` domain in generated
Verilog code.

I expect most users to only need to `import` from `sentinel_cpu.top` to create
their SoC:

```{testcode}
from amaranth import Elaboratable
from sentinel_cpu.top import Top

class MySoC(Elaboratable):
    def __init__(self):
        self.cpu = Top()
        ...

    def elaborate(self, plat):
        m = Module()
        m.submodules.cpu = self.cpu
        ...
```

Since the Sentinel top-level is only a CPU, not a full computer system,
_the user must provide some sort of memory, and I/O to effectively run
programs_. One common way to do this is to connect Sentinel's Wishbone bus to
a Wishbone address decoder, behind which memory and I/O live.

See the {class}`~examples.attosoc.AttoSoC` `class`, and the corresponding
[section](./quickstart.md#a-full-example-soc-in-amaranth) in the Quickstart,
for a full working example.

## Public API

```{eval-rst}
.. automodule:: sentinel_cpu
```

```{eval-rst}
.. automodule:: sentinel_cpu.top
    :members:
```

```{eval-rst}
.. automodule:: sentinel_cpu.gen
    :members:
```