# MAX2771 Three-Wire SPI IP

This directory contains the dedicated MAX2771 serial engine. It is independent
of the generic `pmod_spi` controller and implements the MAX2771 transaction
format directly.

Primary references:

- [MAX2771 data sheet](https://www.analog.com/media/en/technical-documentation/data-sheets/max2771.pdf), Serial Interface and Table 15
- [MAX2771 EV kit data sheet and schematic](https://www.analog.com/media/en/technical-documentation/data-sheets/MAX2771EVKIT.pdf)

## Protocol

Every command is one 48-SCLK frame while `CSN` is low:

```text
clocks 0..11   A[11:0], MSB first; A[11:4] are zero
clock 12       R/W: 1 read, 0 write
clocks 13..15  three turnaround clocks
clocks 16..47  D[31:0], MSB first
```

`SCLK` idles low. Both sides sample on rising edges and change data on falling
edges. `SDATA` is one bidirectional line, not separate MOSI and MISO signals.
For reads, the host releases `SDATA` on the falling edge after the R/W bit and
keeps it as an input through the three turnaround clocks and 32 data clocks.

The divider uses ceiling division so SCLK never exceeds the 4 MHz data-sheet
limit:

```text
board       fabric clock  half-period  SCLK       period
Genesys 2   50 MHz        7 cycles     3.571 MHz  280 ns
VCU118      100 MHz       13 cycles    3.846 MHz  260 ns
```

Both satisfy the 250 ns minimum period. The engine also enforces at least one
half-period for CS setup and hold and at least 100 ns between transactions.

## MMIO

The TileLink wrapper is at `0x10016000` on both FPGA targets.

| Offset | Name | Description |
| --- | --- | --- |
| `0x00` | COMMAND | bits 3:0 address, bit 8 read; write starts a frame |
| `0x04` | WRITE_DATA | 32-bit register write value |
| `0x08` | READ_DATA | last 32-bit register read value |
| `0x0c` | STATUS | bit 0 ready, bit 1 busy |
| `0x10` | INPUT_CLOCK_HZ | configured board fabric clock |
| `0x14` | SCLK_HZ | actual divided serial clock |
| `0x18` | HALF_PERIOD | fabric cycles per SCLK half-period |
| `0x1c` | IDENT | `0x4d415831` (`MAX1`) |

## Simulation

The self-checking testbench models the MAX2771 side of the resolved SDATA wire
and covers writes, reads, turnaround high impedance, contention, frame order,
frame length, CS timing, and both board clock parameters.

```bash
make -C hardware/ip/max2771_spi test
```

This target uses `vlog` and `vsim`. Set `QUESTA=/path/to/questa` when they are
not on `PATH`.