SPI Slave Asynchronous Driver

In the serial peripheral interface (SPI) slave asynchronous driver, a callback function can be registered in the driver by the application and triggered when the transfer is done. The driver io_read/io_write() function will attempt to read/write the data from/to the master device.

When data is written through the I/O writing function, the data buffer pointer and its size is logged internally by the driver. The data is sent character by character in background interrupts. When all data in the buffer is sent, a callback is invoked to notify that it's done.

When the driver is enabled, the characters shifted in will be filled to a receiving ring buffer, then the available data can be read out through the I/O reading function. On each character's reception a callback is invoked.

In some cases, the SS deactivation is considered. It's notified through a completion callback with status code zero. When status code is lower than zero, an error is indicated.

Refer SPI Drivers for more detailed SPI basics.

Summary of the API's Functional Features

The API provides functions to:
  • Initialize and deinitialize the driver and associated hardware

  • Register I/O descriptor

  • Enable or disable SPI slave

  • Hookup callback handlers on TX complete, RX complete, or error events

  • Read/Write message to/from the master

Summary of Configuration Options

Below is a list of the main SPI slave parameters that can be configured in START. Many of these parameters are used by the spi_s_async_init function when initializing the driver and underlying hardware. Most of the initialized values can be overridden.
  • Select character size

  • Which clock source is used

Driver Implementation Description

After the SPI hardware initialization, the spi_s_async_get_io_descriptor function is needed to register an I/O descriptor. Then use spi_s_async_register_callback to register a callback function for the RX/TX complete, and enable the SPI hardware. At the end, start the read/write operation.

Limitations

When received data is not read promptly, the ring buffer is used. In this case the oldest characters will be overwritten by the newest ones.

Known Issues and Workarounds

When writing data through the SPI slave, the time that the data appears on the data line depends on the SPI hardware, and previous writing state, since there can be data in output fifo filled by previous broken transmitting. The number of such dummy/broken characters is limited by the hardware. Whether these dummy/broken characters can be flushed is also limited by the hardware.

Example of Usage

The following shows a simple example of using the SPI slave. The SPI slave must have been initialized by spi_s_async_init. This initialization will configure the operation of the SPI slave.

The example registers an I/O descriptor and enables the hardware. Then it registers a callback for RX complete and finally starts a reading operation.

          /**
           * Example of using SPI_0 to write "Hello World" using the I/O abstraction.
            
           * Since the driver is asynchronous we need to use statically allocated memory for string
           * because driver initiates transfer and then returns before the transmission is completed.
            
           * Once transfer has been completed the tx_cb function will be called.
           */
          static uint8_t example_SPI_0[12] = "Hello World!";
          static void complete_cb_SPI_0(const struct spi_s_async_descriptor *const desc)
          {
              /* Transfer completed */
          }
          void SPI_0_example(void)
          {
              struct io_descriptor *io;
              spi_s_async_get_io_descriptor(&SPI_0, &io);
              spi_s_async_register_callback(&SPI_0, SPI_S_CB_TX, (FUNC_PTR)complete_cb_SPI_0);
              spi_s_async_enable(&SPI_0);
              io_write(io, example_SPI_0, 12);
          }
        

Dependencies

  • The SPI slave peripheral and its related I/O lines and clocks

  • The NVIC must be configured so that SPI interrupt requests are periodically serviced