# SPI Slave

# SPI Slave

This module includes the platform abstraction for SPI slave communication.

## Summary

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaa4fd4b1d62b8b57a1b2816e3e6fa5334)(void *aContext, uint8_t *aOutputBuf, uint16_t aOutputBufLen, uint8_t *aInputBuf, uint16_t aInputBufLen, uint16_t aTransactionLength)` | typedef `bool(*` Indicates that a SPI transaction has completed with the given length. |
| `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaac978fd9928e43b653654ace47263554)(void *aContext)` | typedef `void(*` Invoked after a transaction complete callback is called and returns `TRUE` to do any further processing required. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga3b386f4b585e8deafa475c873d13a532(void)` | `void` Shutdown and disable the SPI slave interface. |
| `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga2fe1b89ff527c7b88f5bee108d5318f3(https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaa4fd4b1d62b8b57a1b2816e3e6fa5334 aCompleteCallback, https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaac978fd9928e43b653654ace47263554 aProcessCallback, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Initialize the SPI slave interface. |
| `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6(uint8_t *aOutputBuf, uint16_t aOutputBufLen, uint8_t *aInputBuf, uint16_t aInputBufLen, bool aRequestTransactionFlag)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Prepare data for the next SPI transaction. |

## Typedefs

### otPlatSpiSlaveTransactionCompleteCallback

```
bool(* otPlatSpiSlaveTransactionCompleteCallback)(void *aContext, uint8_t *aOutputBuf, uint16_t aOutputBufLen, uint8_t *aInputBuf, uint16_t aInputBufLen, uint16_t aTransactionLength)
```
Indicates that a SPI transaction has completed with the given length.

The data written to the slave has been written to the pointer indicated by the `aInputBuf` argument to the previous call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6`.

Once this function is called, `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6` is invalid and must be called again for the next transaction to be valid.

Note that this function is always called at the end of a transaction, even if `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6` has not yet been called. In such cases, `aOutputBufLen` and `aInputBufLen` will be zero.

This callback can be called from ISR context. The return value from this function indicates if any further processing is required. If `TRUE` is returned the platform spi-slave driver implementation must invoke the transaction process callback (`aProcessCallback` set in `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga2fe1b89ff527c7b88f5bee108d5318f3`) which unlike this callback must be called from the same OS context that any other OpenThread API/callback is called.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | Context pointer passed into `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga2fe1b89ff527c7b88f5bee108d5318f3`. | | `[in] aOutputBuf` | Value of `aOutputBuf` from last call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6`. | | `[in] aOutputBufLen` | Value of `aOutputBufLen` from last call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6`. | | `[in] aInputBuf` | Value of aInputBuf from last call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6`. | | `[in] aInputBufLen` | Value of aInputBufLen from last call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6` | | `[in] aTransactionLength` | Length of the completed transaction, in bytes. | |
| **Returns** | TRUE if after this call returns the platform should invoke the process callback `aProcessCallback`, FALSE if there is nothing to process and no need to invoke the process callback. |

### otPlatSpiSlaveTransactionProcessCallback

```
void(* otPlatSpiSlaveTransactionProcessCallback)(void *aContext)
```
Invoked after a transaction complete callback is called and returns `TRUE` to do any further processing required.

Unlike `otPlatSpiSlaveTransactionCompleteCallback` which can be called from any OS context (e.g., ISR), this callback MUST be called from the same OS context as any other OpenThread API/callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | Context pointer passed into `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga2fe1b89ff527c7b88f5bee108d5318f3`. | |

## Functions

### otPlatSpiSlaveDisable

```
void otPlatSpiSlaveDisable(
  void
)
```
Shutdown and disable the SPI slave interface.

### otPlatSpiSlaveEnable

```
otError otPlatSpiSlaveEnable(
  otPlatSpiSlaveTransactionCompleteCallback aCompleteCallback,
  otPlatSpiSlaveTransactionProcessCallback aProcessCallback,
  void *aContext
)
```
Initialize the SPI slave interface.

Note that SPI slave is not fully ready until a transaction is prepared using `otPlatSPISlavePrepareTransaction()`.

If `otPlatSPISlavePrepareTransaction() is not called before the master begins a transaction, the resulting SPI transaction will send all`0xFF\` bytes and discard all received bytes.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aCompleteCallback` | Pointer to transaction complete callback. | | `[in] aProcessCallback` | Pointer to process callback. | | `[in] aContext` | Context pointer to be passed to callbacks. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully enabled the SPI Slave interface. | | `OT_ERROR_ALREADY` | SPI Slave interface is already enabled. | | `OT_ERROR_FAILED` | Failed to enable the SPI Slave interface. | |

### otPlatSpiSlavePrepareTransaction

```
otError otPlatSpiSlavePrepareTransaction(
  uint8_t *aOutputBuf,
  uint16_t aOutputBufLen,
  uint8_t *aInputBuf,
  uint16_t aInputBufLen,
  bool aRequestTransactionFlag
)
```
Prepare data for the next SPI transaction.

Data pointers MUST remain valid until the transaction complete callback is called by the SPI slave driver, or until after the next call to `https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1gaf51c0fd960e6874b866e97c7225c24e6`.

May be called more than once before the SPI master initiates the transaction. Each *successful* call to this function will cause the previous values from earlier calls to be discarded.

Not calling this function after a completed transaction is the same as if this function was previously called with both buffer lengths set to zero and `aRequestTransactionFlag` set to `false`.

Once `aOutputBufLen` bytes of `aOutputBuf` has been clocked out, the MISO pin shall be set high until the master finishes the SPI transaction. This is the functional equivalent of padding the end of `aOutputBuf` with `0xFF` bytes out to the length of the transaction.

Once `aInputBufLen` bytes of aInputBuf have been clocked in from MOSI, all subsequent values from the MOSI pin are ignored until the SPI master finishes the transaction.

Note that even if `aInputBufLen` or `aOutputBufLen` (or both) are exhausted before the SPI master finishes a transaction, the ongoing size of the transaction must still be kept track of to be passed to the transaction complete callback. For example, if `aInputBufLen` is equal to 10 and `aOutputBufLen` equal to 20 and the SPI master clocks out 30 bytes, the value 30 is passed to the transaction complete callback.

If a `NULL` pointer is passed in as `aOutputBuf` or `aInputBuf` it means that that buffer pointer should not change from its previous/current value. In this case, the corresponding length argument should be ignored. For example, `otPlatSpiSlavePrepareTransaction(NULL, 0, aInputBuf, aInputLen, false)` changes the input buffer pointer and its length but keeps the output buffer pointer same as before.

Any call to this function while a transaction is in progress will cause all of the arguments to be ignored and the return value to be `OT_ERROR_BUSY`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aOutputBuf` | Data to be written to MISO pin | | `[in] aOutputBufLen` | Size of the output buffer, in bytes | | `[in] aInputBuf` | Data to be read from MOSI pin | | `[in] aInputBufLen` | Size of the input buffer, in bytes | | `[in] aRequestTransactionFlag` | Set to true if host interrupt should be set | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Transaction was successfully prepared. | | `OT_ERROR_BUSY` | A transaction is currently in progress. | | `OT_ERROR_INVALID_STATE` | [otPlatSpiSlaveEnable()](https://openthread.io/reference/group/plat-spi-slave#group__plat-spi-slave_1ga2fe1b89ff527c7b88f5bee108d5318f3) hasn't been called. | |

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).