SPI application (app/spi-app.c and app/spi-slv-app.c)
==============================

@tableofcontents

SPI application demonstrates how to access/manipulate Always On (AON) SPI from
the SPE/AON processor. SPI2 is in AON domain for both Jetson AGX Orin and Orin Nano.
SPE/AON processor supports both SPI master and slave driver.
Note that the application can utilize either the SPI master or SPI slave mode, but not both simultaneously.
In both demonstrations, the SPI frequency is configured to be 12MHz.
The SPI master application performs a loopback test, while the SPI slave application requires an SPI master
to drive it for sending and receiving test data. Both applications send predefined bytes and compare the sent
bytes with the received ones, displaying a successful message upon a match.

@note It is required to compile device tree and flash board to have device tree
updated after making kernel device tree changes as described in following
sections.


# Jetson AGX Orin

## Hardware Configuration

SPI Master

User must short MISO and MOSI signals (follow below sections for pin map) in
order to successfully run this app.
SPI2 signals are available at connector J3 with below pin mappings.

- Pin E61 - CLK
- Pin D62 - MISO
- Pin F60 - MOSI
- Pin D60 - CS0

SPI Slave

User must connect a SPI master device to SPI2 slave pins available at connector J3 with below pin mappings.


- CLK (Master)  -> Pin E61 (CLK) (Slave)
- MISO (Master) <- Pin D62 (MISO) (Slave)
- MOSI (Master) -> Pin F60 (MOSI) (Slave)
- CS0 (Master)  -> Pin D60 (CS0) (Slave)

@note SPI2 operates at a high level of 1.8V. Ensure your SPI master also uses 1.8V, or add a level shifter if using 3.3V.

## Software Configuration

1. Pinmuxing updates are recommended via generating new dtsi files using
the pinmux spreadsheet.  For the purpose of performing a quick test, the pinmux files can be manually
updated by editing `${L4T}/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3701-0000-a04.dtsi`.

   SPI Master:

            --- a/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3701-0000-a04.dtsi
            +++ b/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3701-0000-a04.dtsi
            @@ -915,18 +915,18 @@

                                    spi2_sck_pcc0 {
                                            nvidia,pins = "spi2_sck_pcc0";
            -                               nvidia,function = "rsvd1";
            -                               nvidia,pull = <TEGRA_PIN_PULL_UP>;
            -                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            +                               nvidia,function = "spi2";
            +                               nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            +                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_miso_pcc1 {
                                            nvidia,pins = "spi2_miso_pcc1";
            -                               nvidia,function = "rsvd1";
            -                               nvidia,pull = <TEGRA_PIN_PULL_UP>;
            +                               nvidia,function = "spi2";
            +                               nvidia,pull = <TEGRA_PIN_PULL_NONE>;
                                            nvidia,tristate = <TEGRA_PIN_ENABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_ENABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
            @@ -935,20 +935,20 @@

                                    spi2_mosi_pcc2 {
                                            nvidia,pins = "spi2_mosi_pcc2";
            -                               nvidia,function = "rsvd1";
            -                               nvidia,pull = <TEGRA_PIN_PULL_UP>;
            -                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            +                               nvidia,function = "spi2";
            +                               nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            +                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_cs0_pcc3 {
                                            nvidia,pins = "spi2_cs0_pcc3";
            -                               nvidia,function = "rsvd1";
            -                               nvidia,pull = <TEGRA_PIN_PULL_UP>;
            -                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            +                               nvidia,function = "spi2";
            +                               nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            +                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

   SPI Slave:

            --- a/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3701-0000-a04.dtsi
            +++ b/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3701-0000-a04.dtsi
            @@ -899,7 +899,7 @@

                                    spi2_sck_pcc0 {
                                            nvidia,pins = "spi2_sck_pcc0";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_UP>;
                                            nvidia,tristate = <TEGRA_PIN_ENABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            @@ -909,17 +909,17 @@

                                    spi2_miso_pcc1 {
                                            nvidia,pins = "spi2_miso_pcc1";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_UP>;
            -                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            +                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_mosi_pcc2 {
                                            nvidia,pins = "spi2_mosi_pcc2";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_UP>;
                                            nvidia,tristate = <TEGRA_PIN_ENABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_ENABLE>;
            @@ -929,7 +929,7 @@

                                    spi2_cs0_pcc3 {
                                            nvidia,pins = "spi2_cs0_pcc3";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_UP>;
                                            nvidia,tristate = <TEGRA_PIN_ENABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_ENABLE>;

2. Update gpio configuration as below in `${L4T}/bootloader/tegra234-mb1-bct-gpio-p3701-0000-a04.dtsi`:

            --- a/bootloader/tegra234-mb1-bct-gpio-p3701-0000-a04.dtsi
            +++ b/bootloader/tegra234-mb1-bct-gpio-p3701-0000-a04.dtsi
            @@ -125,10 +125,6 @@
                                            TEGRA234_AON_GPIO(EE, 6)
                                            TEGRA234_AON_GPIO(EE, 2)
                                            TEGRA234_AON_GPIO(EE, 4)
            -                               TEGRA234_AON_GPIO(CC, 0)
            -                               TEGRA234_AON_GPIO(CC, 1)
            -                               TEGRA234_AON_GPIO(CC, 2)
            -                               TEGRA234_AON_GPIO(CC, 3)
                                            TEGRA234_AON_GPIO(AA, 0)

3. Modify firewall setting in `${L4T}/bootloader/tegra234-mb2-bct-scr-p3701-0000-override.dts` to allow SPE to read/write to the SPI2 register.

            +++ b/bootloader/tegra234-mb2-bct-scr-p3701-0000-override.dts
            @@ -24,6 +24,11 @@
                           value = <0x18000606>;
                       };

            +          reg@2135 { /* CLK_RST_CONTROLLER_AON_SCR_SPI2_0 */
            +              exclusion-info = <3>;
            +              value = <0x30001410>;
            +          };
            +
                       reg@5114 { /* CBB_CENTRAL_CBB_FIREWALL_PWM5_BLF, READ_CTL */

4. For SPI Master app, In `soc/t23x/target_specific.mk`, set `ENABLE_SPI_APP := 1` and rebuild the application. Copy the output to `${L4T}/bootloader/spe_t234.bin`.

   For SPI Slave app, In `soc/t23x/target_specific.mk`, set `ENABLE_SPI_SLV_APP := 1` and rebuild the application. Copy the output to `${L4T}/bootloader/spe_t234.bin`.


5. Reflash all partitions to ensure that the pinmux and firewall settings are updated on the board.

@note For SPI Slave app, make sure SPI master is setup first before slave because SCLK is provided from SPI master.

# Jetson Orin Nano

## Hardware Configuration

SPI Master

User must short MISO and MOSI signals (follow below sections for pin map) in
order to successfully run this app.
SPI2 signals are available at connector J2 with below pin mappings.

- Pin 126 - CLK
- Pin 127 - MISO
- Pin 128 - MOSI
- Pin 130 - CS0

SPI Slave

User must connect a SPI master device to SPI2 slave pins available at connector J2 with below pin mappings.


- CLK (Master)  -> Pin 126 (CLK) (Slave)
- MISO (Master) <- Pin 127 (MISO) (Slave)
- MOSI (Master) -> Pin 128 (MOSI) (Slave)
- CS0 (Master)  -> Pin 130 (CS0) (Slave)

@note SPI2 operates at a high level of 1.8V. Ensure your SPI master also uses 1.8V, or add a level shifter if using 3.3V.

## Software Configuration

1. Pinmuxing updates are recommended via generating new dtsi files using
the pinmux spreadsheet.  For the purpose of performing a quick test, the pinmux files can be manually
updated by editing `${L4T}/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3767-dp-a03.dtsi`:

   SPI Master:

            --- a/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3767-dp-a03.dtsi
            +++ b/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3767-dp-a03.dtsi
            @@ -608,7 +608,7 @@

                                    spi2_sck_pcc0 {
                                            nvidia,pins = "spi2_sck_pcc0";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
                                            nvidia,tristate = <TEGRA_PIN_DISABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            @@ -618,17 +618,17 @@

                                    spi2_miso_pcc1 {
                                            nvidia,pins = "spi2_miso_pcc1";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            -                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            +                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_mosi_pcc2 {
                                            nvidia,pins = "spi2_mosi_pcc2";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
                                            nvidia,tristate = <TEGRA_PIN_DISABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_DISABLE>;
           @@ -638,7 +638,7 @@

                                   spi2_cs0_pcc3 {
                                            nvidia,pins = "spi2_cs0_pcc3";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
                                            nvidia,tristate = <TEGRA_PIN_DISABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_DISABLE>;

   SPI Slave:

            --- a/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3767-dp-a03.dtsi
            +++ b/bootloader/generic/BCT/tegra234-mb1-bct-pinmux-p3767-dp-a03.dtsi
            @@ -608,17 +608,17 @@

                                    spi2_sck_pcc0 {
                                            nvidia,pins = "spi2_sck_pcc0";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            -                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            +                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_miso_pcc1 {
                                            nvidia,pins = "spi2_miso_pcc1";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
                                            nvidia,tristate = <TEGRA_PIN_DISABLE>;
                                            nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            @@ -628,20 +628,20 @@

                                    spi2_mosi_pcc2 {
                                            nvidia,pins = "spi2_mosi_pcc2";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            -                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            +                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

                                    spi2_cs0_pcc3 {
                                            nvidia,pins = "spi2_cs0_pcc3";
            -                               nvidia,function = "rsvd1";
            +                               nvidia,function = "spi2";
                                            nvidia,pull = <TEGRA_PIN_PULL_NONE>;
            -                               nvidia,tristate = <TEGRA_PIN_DISABLE>;
            -                               nvidia,enable-input = <TEGRA_PIN_DISABLE>;
            +                               nvidia,tristate = <TEGRA_PIN_ENABLE>;
            +                               nvidia,enable-input = <TEGRA_PIN_ENABLE>;
                                            nvidia,io-high-voltage = <TEGRA_PIN_DISABLE>;
                                            nvidia,lpdr = <TEGRA_PIN_DISABLE>;
                                    };

2. Update gpio configuration as below in `${L4T}/bootloader/tegra234-mb1-bct-gpio-p3767-dp-a03.dtsi`:

          --- a/bootloader/tegra234-mb1-bct-gpio-p3767-dp-a03.dtsi
          +++ b/bootloader/tegra234-mb1-bct-gpio-p3767-dp-a03.dtsi
          @@ -91,13 +91,9 @@
                                          TEGRA234_AON_GPIO(EE, 4)
                                          >;
                                  gpio-output-low = <
          -                               TEGRA234_AON_GPIO(CC, 0)
          -                               TEGRA234_AON_GPIO(CC, 2)
          -                               TEGRA234_AON_GPIO(CC, 3)
                                          TEGRA234_AON_GPIO(AA, 4)
                                          >;
                                  gpio-output-high = <
          -                               TEGRA234_AON_GPIO(CC, 1)
                                          TEGRA234_AON_GPIO(AA, 5)
                                          TEGRA234_AON_GPIO(BB, 3)
                                          >;


3. Modify firewall setting in `${L4T}/bootloader/tegra234-mb2-bct-scr-p3767-0000.dts` to allow SPE to read/write to the SPI2 register.

            +++ b/bootloader/tegra234-mb2-bct-scr-p3767-0000.dts
            @@ -810,6 +810,10 @@
                                  exclusion-info = <0>;
                                  value = <0x00000000>;
                                  };
            +                     reg@2135 { /* CLK_RST_CONTROLLER_AON_SCR_SPI2_0 */
            +                     exclusion-info = <3>;
            +                     value = <0x30001410>;
            +                     };
                                  reg@2228 { /* CLK_RST_CONTROLLER_ERR_COLLATOR_FSI_SCR_EC_SCR_0 */
                                  exclusion-info = <0>;

4. For SPI Master app, In `soc/t23x/target_specific.mk`, set `ENABLE_SPI_APP := 1` and rebuild the application. Copy the output to `${L4T}/bootloader/spe_t234.bin`.

  For SPI Slave app, In `soc/t23x/target_specific.mk`, set `ENABLE_SPI_SLV_APP := 1` and rebuild the application. Copy the output to `${L4T}/bootloader/spe_t234.bin`.

5. Reflash all partitions to ensure that the pinmux and firewall settings are updated on the board.

@note For SPI Slave app, make sure SPI master is setup first before slave because SCLK is provided from SPI master.

# Result
The demo app sends predefined data and considers the test successful if it retrieves the same data.
For the SPI Master application, it will display "SPI test successful" and for the SPI Slave
application, it will display "SPI Slave test passed."
