.. include:: ../substitutions.rst
.. include:: stdout.rst

SPI
===

The i.MX RT1170 processor includes six Low Power SPI (LPSPI) controllers. In the current |release-name| release, only ``lpspi5`` (``spi@40c2c000``) is enabled and exposed on the |product| module, routed to the |product-cb| carrier board's phyCORE connector via its ``SCK``, ``SDI`` (MISO), ``SDO`` (MOSI), and three chip-select (``PCS0``-``PCS2``) signals. ``lpspi1`` is present in devicetree but disabled by default, since its pins conflict with ``lpuart5``.

For detailed hardware-level information, refer to the *7.5 SPI* chapter in the |hw-manual-link|.

You can inspect and exercise ``lpspi5`` directly from the Zephyr shell using the built-in ``spi`` commands, without writing any application code.

Requirements
------------

* Jumper Wire (Male to Male)

Shell Usage
-----------

The |product-cb| carrier board provides a easy access SPI signal for a loopback testing on connector X8, wire pin 19 (``X_LPSPI5_SDO``) directly to pin 21 (``X_LPSPI5_SDI``).

Configuring the SPI Bus
~~~~~~~~~~~~~~~~~~~~~~~~

Before transferring data, configure the bus frequency (in Hz) with ``spi conf``:

.. code-block:: console
   :substitutions:

   |target-prompt| spi conf lpspi5 1000000

This configures ``lpspi5`` for a 1 MHz clock in SPI mode 0 (CPOL=0, CPHA=0). Optionally, append a settings string to select a different SPI mode:

.. list-table:: **SPI Mode Settings**
   :header-rows: 1

   * - Mode
     - CPOL
     - CPHA
     - ``spi conf`` Setting
   * - 0
     - 0
     - 0
     - (none)
   * - 1
     - 0
     - 1
     - ``h``
   * - 2
     - 1
     - 0
     - ``o``
   * - 3
     - 1
     - 1
     - ``oh``

For example, to configure ``lpspi5`` for a 10 MHz clock in SPI mode 3:

.. code-block:: console
   :substitutions:

   |target-prompt| spi conf lpspi5 10000000 oh

Transferring Data
~~~~~~~~~~~~~~~~~~

With the bus configured, use ``spi transceive`` to send bytes out ``SDO`` while simultaneously capturing whatever arrives on ``SDI``:

.. code-block:: console
   :substitutions:

   |target-prompt| spi transceive lpspi5 0xde 0xad 0xbe 0xef

.. code-block:: none
   :caption: Expected Output

   TX:
   00000000: de ad be ef                                      |....             |
   RX:
   00000000: de ad be ef                                      |....             |

Because ``SDO`` is looped back to ``SDI``, the received (``RX``) bytes match the transmitted (``TX``) bytes exactly.

Assigning a Software Chip-Select
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a device controlled by a GPIO chip-select rather than one of ``lpspi5``'s three hardware ``PCS`` lines, bind a GPIO pin with ``spi cs`` before configuring or transferring data:

.. code-block:: console
   :substitutions:

   |target-prompt| spi cs lpspi5 gpio9 3 0x01

This assigns pin 3 on ``gpio9`` as the chip-select used by subsequent ``spi transceive`` calls on ``lpspi5``.

Loopback Testing from Application Code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To exercise ``lpspi5`` from application code rather than the shell, add a child device node to ``&lpspi5`` in the sample's board overlay (``app/rt1170/boards/phyboard_atlas_mimxrt1176_cm7.overlay``):

.. code-block:: none

   &lpspi5 {
           my_spi_dev: my_spi_dev@0 {
                   compatible = "vnd,spi-device";   /* generic placeholder binding */
                   reg = <0>;                       /* CS index on this bus */
                   spi-max-frequency = <1000000>;   /* 1 MHz, adjust to your device */
           };
   };

``vnd,spi-device`` is a placeholder compatible for illustration only. Replace it with your actual device's Zephyr binding, or a custom binding you define under ``dts/bindings/``.

``lpspi5``'s pinctrl and chip-selects are already enabled by default, so no additional ``&pinctrl`` block is required here. With the wiring from the `Shell Usage`_ section above still in place (pin 19 to pin 21 on connector X8), obtain a ``struct spi_dt_spec`` for ``my_spi_dev`` via ``SPI_DT_SPEC_GET()`` and call ``spi_transceive_dt()`` from your driver code; bytes written out ``SDO`` will read back on ``SDI``, just as with the shell-based example above.

After editing the overlay, rebuild and reflash the application as described in |ref-build-fw|.

.. include:: ../../common/support-disclaimer-us.rst