# 软件 9-bit SPI 示例

## 功能说明

本示例演示在 `arcs_evb` 和 `venusa_rd_evb` 上使用 `spi_sw0`，通过 GPIO 模拟 9-bit SPI 主机发送。
示例仅使用 SCLK、MOSI 和低有效 CS，不配置 MISO，也不使用硬件 SPI 控制器。

软件 SPI 使用同步 polling 传输。`lisa_spi_write()` 返回时，本次发送已经完成，不需要 callback 或信号量。

## 硬件连接

两个板型使用相同引脚：

| SPI 信号 | GPIO 引脚 | 方向 |
|---|---|---|
| SCLK | PA10 / GPIOA 10 | 输出 |
| MOSI | PA11 / GPIOA 11 | 输出 |
| CS | PA12 / GPIOA 12 | 输出，低有效 |

本例中的 MOSI 也可称为 SDA，但只作为单向数据输出使用。

使用逻辑分析仪时，建议按以下方式连接：

```text
CH0 -> PA10 / SCLK
CH1 -> PA11 / MOSI
CH2 -> PA12 / CS
GND -> GND
```

## 示例步骤

1. 重写 `lisa_gpioa_pinmux()`，将 PA10、PA11 和 PA12 配置为 GPIOA。
2. 获取 `spi_sw0` 和 `gpioa` 设备。
3. 调用 `lisa_spi_sw_configure_io()` 配置软件 SPI 引脚。
4. 配置 Mode 0、MSB first、62500 Hz 和 9-bit frame。
5. 调用 `lisa_spi_write()` 发送 4 个 9-bit frame。

## 9-bit 数据组织

每个 9-bit frame 使用一个 `uint16_t` 存储，仅低 9 位有效：

```c
static const uint16_t tx_frames[] = {
    0x011U,
    0x122U,
    0x055U,
    0x1AAU,
};

lisa_spi_write(spi_dev,
               (const uint8_t *)tx_frames,
               ARRAY_SIZE(tx_frames));
```

`lisa_spi_write()` 的 `len` 参数表示 frame 数量，不是缓冲区字节数。因此这里传入 `4`，不能传入
`sizeof(tx_frames)`（其值为 8）。

预期一次 CS transaction 内发送 4 个 frame，每个 frame 产生 9 个时钟，共产生 36 个 SCLK。

## 配置说明

关键 Kconfig 配置如下：

```kconfig
CONFIG_LISA_DEVICE=y
CONFIG_LISA_GPIO_DEVICE=y
CONFIG_LISA_GPIOA=y
CONFIG_LISA_SPI_DEVICE=y
CONFIG_LISA_SPI_SW0=y
```

本示例不启用 `CONFIG_LISA_SPI0`、`CONFIG_LISA_SPI1` 或 `CONFIG_LISA_SPI2`。

## 编译

```{eval-rst}
.. include:: /sample_build.rst
```

构建 `arcs_evb`：

```bash
./build.sh -C -S samples/drivers/devices/lisa_spi/software_spi -DBOARD=arcs_evb
```

构建 `venusa_rd_evb`：

```bash
./build.sh -C -S samples/drivers/devices/lisa_spi/software_spi -DBOARD=venusa_rd_evb
```

## 烧录

```{eval-rst}
.. include:: /sample_flash.rst
```

## 预期输出

```text
=== LISA software 9-bit SPI example ===
Software SPI pins: SCLK=PA10, MOSI=PA11, CS=PA12
Software SPI configured: mode=0, frequency=62500 Hz, data_bits=9
Software SPI transfer success: 4 frames
Software 9-bit SPI example passed
```

## 预期波形

- SPI Mode 0，SCLK 空闲为低。
- MSB first。
- CS 低有效，一次 `lisa_spi_write()` 对应一次完整 transaction。
- 依次发送 `0x011`、`0x122`、`0x055`、`0x1AA`。
- 每个 frame 恰好有 9 个 SCLK，总计 36 个 SCLK。

## 注意事项

1. 软件 SPI 仅支持同步 polling，不支持 DMA、中断传输和 callback。
2. 软件 SPI 的实际频率受 GPIO API 和 CPU 执行开销影响，不会高于配置频率。
3. 本示例只发送数据，不配置 MISO，因此不演示读取或全双工传输。
4. `LISA_SPI_FLAG_HARDWARE_CS` 在 `spi_sw0` 中表示由软件 SPI backend 自动控制配置的 CS GPIO。