| 1 | /* SPDX-License-Identifier: BSD-3-Clause */ |
| 2 | /* |
| 3 | * Copyright (C) 2023 OpenSynergy GmbH |
| 4 | * Copyright (C) 2025 Qualcomm Innovation Center, Inc. All rights reserved. |
| 5 | */ |
| 6 | #ifndef _LINUX_VIRTIO_VIRTIO_SPI_H |
| 7 | #define _LINUX_VIRTIO_VIRTIO_SPI_H |
| 8 | |
| 9 | #include "standard-headers/linux/types.h" |
| 10 | #include "standard-headers/linux/virtio_config.h" |
| 11 | #include "standard-headers/linux/virtio_ids.h" |
| 12 | #include "standard-headers/linux/virtio_types.h" |
| 13 | |
| 14 | /* Sample data on trailing clock edge */ |
| 15 | #define VIRTIO_SPI_CPHA _BITUL(0) |
| 16 | /* Clock is high when IDLE */ |
| 17 | #define VIRTIO_SPI_CPOL _BITUL(1) |
| 18 | /* Chip Select is active high */ |
| 19 | #define VIRTIO_SPI_CS_HIGH _BITUL(2) |
| 20 | /* Transmit LSB first */ |
| 21 | #define VIRTIO_SPI_MODE_LSB_FIRST _BITUL(3) |
| 22 | /* Loopback mode */ |
| 23 | #define VIRTIO_SPI_MODE_LOOP _BITUL(4) |
| 24 | |
| 25 | /** |
| 26 | * struct virtio_spi_config - All config fields are read-only for the |
| 27 | * Virtio SPI driver |
| 28 | * @cs_max_number: maximum number of chipselect the host SPI controller |
| 29 | * supports. |
| 30 | * @cs_change_supported: indicates if the host SPI controller supports to toggle |
| 31 | * chipselect after each transfer in one message: |
| 32 | * 0: unsupported, chipselect will be kept in active state throughout the |
| 33 | * message transaction; |
| 34 | * 1: supported. |
| 35 | * Note: Message here contains a sequence of SPI transfers. |
| 36 | * @tx_nbits_supported: indicates the supported number of bit for writing: |
| 37 | * bit 0: DUAL (2-bit transfer), 1 for supported |
| 38 | * bit 1: QUAD (4-bit transfer), 1 for supported |
| 39 | * bit 2: OCTAL (8-bit transfer), 1 for supported |
| 40 | * other bits are reserved as 0, 1-bit transfer is always supported. |
| 41 | * @rx_nbits_supported: indicates the supported number of bit for reading: |
| 42 | * bit 0: DUAL (2-bit transfer), 1 for supported |
| 43 | * bit 1: QUAD (4-bit transfer), 1 for supported |
| 44 | * bit 2: OCTAL (8-bit transfer), 1 for supported |
| 45 | * other bits are reserved as 0, 1-bit transfer is always supported. |
| 46 | * @bits_per_word_mask: mask indicating which values of bits_per_word are |
| 47 | * supported. If not set, no limitation for bits_per_word. |
| 48 | * @mode_func_supported: indicates the following features are supported or not: |
| 49 | * bit 0-1: CPHA feature |
| 50 | * 0b00: invalid, should support as least one CPHA setting |
| 51 | * 0b01: supports CPHA=0 only |
| 52 | * 0b10: supports CPHA=1 only |
| 53 | * 0b11: supports CPHA=0 and CPHA=1. |
| 54 | * bit 2-3: CPOL feature |
| 55 | * 0b00: invalid, should support as least one CPOL setting |
| 56 | * 0b01: supports CPOL=0 only |
| 57 | * 0b10: supports CPOL=1 only |
| 58 | * 0b11: supports CPOL=0 and CPOL=1. |
| 59 | * bit 4: chipselect active high feature, 0 for unsupported and 1 for |
| 60 | * supported, chipselect active low is supported by default. |
| 61 | * bit 5: LSB first feature, 0 for unsupported and 1 for supported, |
| 62 | * MSB first is supported by default. |
| 63 | * bit 6: loopback mode feature, 0 for unsupported and 1 for supported, |
| 64 | * normal mode is supported by default. |
| 65 | * @max_freq_hz: the maximum clock rate supported in Hz unit, 0 means no |
| 66 | * limitation for transfer speed. |
| 67 | * @max_word_delay_ns: the maximum word delay supported, in nanoseconds. |
| 68 | * A value of 0 indicates that word delay is unsupported. |
| 69 | * Each transfer may consist of a sequence of words. |
| 70 | * @max_cs_setup_ns: the maximum delay supported after chipselect is asserted, |
| 71 | * in ns unit, 0 means delay is not supported to introduce after chipselect is |
| 72 | * asserted. |
| 73 | * @max_cs_hold_ns: the maximum delay supported before chipselect is deasserted, |
| 74 | * in ns unit, 0 means delay is not supported to introduce before chipselect |
| 75 | * is deasserted. |
| 76 | * @max_cs_incative_ns: maximum delay supported after chipselect is deasserted, |
| 77 | * in ns unit, 0 means delay is not supported to introduce after chipselect is |
| 78 | * deasserted. |
| 79 | */ |
| 80 | struct virtio_spi_config { |
| 81 | uint8_t cs_max_number; |
| 82 | uint8_t cs_change_supported; |
| 83 | #define VIRTIO_SPI_RX_TX_SUPPORT_DUAL _BITUL(0) |
| 84 | #define VIRTIO_SPI_RX_TX_SUPPORT_QUAD _BITUL(1) |
| 85 | #define VIRTIO_SPI_RX_TX_SUPPORT_OCTAL _BITUL(2) |
| 86 | uint8_t tx_nbits_supported; |
| 87 | uint8_t rx_nbits_supported; |
| 88 | uint32_t bits_per_word_mask; |
| 89 | #define VIRTIO_SPI_MF_SUPPORT_CPHA_0 _BITUL(0) |
| 90 | #define VIRTIO_SPI_MF_SUPPORT_CPHA_1 _BITUL(1) |
| 91 | #define VIRTIO_SPI_MF_SUPPORT_CPOL_0 _BITUL(2) |
| 92 | #define VIRTIO_SPI_MF_SUPPORT_CPOL_1 _BITUL(3) |
| 93 | #define VIRTIO_SPI_MF_SUPPORT_CS_HIGH _BITUL(4) |
| 94 | #define VIRTIO_SPI_MF_SUPPORT_LSB_FIRST _BITUL(5) |
| 95 | #define VIRTIO_SPI_MF_SUPPORT_LOOPBACK _BITUL(6) |
| 96 | uint32_t mode_func_supported; |
| 97 | uint32_t max_freq_hz; |
| 98 | uint32_t max_word_delay_ns; |
| 99 | uint32_t max_cs_setup_ns; |
| 100 | uint32_t max_cs_hold_ns; |
| 101 | uint32_t max_cs_inactive_ns; |
| 102 | }; |
| 103 | |
| 104 | /** |
| 105 | * struct spi_transfer_head - virtio SPI transfer descriptor |
| 106 | * @chip_select_id: chipselect index the SPI transfer used. |
| 107 | * @bits_per_word: the number of bits in each SPI transfer word. |
| 108 | * @cs_change: whether to deselect device after finishing this transfer |
| 109 | * before starting the next transfer, 0 means cs keep asserted and |
| 110 | * 1 means cs deasserted then asserted again. |
| 111 | * @tx_nbits: bus width for write transfer. |
| 112 | * 0,1: bus width is 1, also known as SINGLE |
| 113 | * 2 : bus width is 2, also known as DUAL |
| 114 | * 4 : bus width is 4, also known as QUAD |
| 115 | * 8 : bus width is 8, also known as OCTAL |
| 116 | * other values are invalid. |
| 117 | * @rx_nbits: bus width for read transfer. |
| 118 | * 0,1: bus width is 1, also known as SINGLE |
| 119 | * 2 : bus width is 2, also known as DUAL |
| 120 | * 4 : bus width is 4, also known as QUAD |
| 121 | * 8 : bus width is 8, also known as OCTAL |
| 122 | * other values are invalid. |
| 123 | * @reserved: for future use. |
| 124 | * @mode: SPI transfer mode. |
| 125 | * bit 0: CPHA, determines the timing (i.e. phase) of the data |
| 126 | * bits relative to the clock pulses.For CPHA=0, the |
| 127 | * "out" side changes the data on the trailing edge of the |
| 128 | * preceding clock cycle, while the "in" side captures the data |
| 129 | * on (or shortly after) the leading edge of the clock cycle. |
| 130 | * For CPHA=1, the "out" side changes the data on the leading |
| 131 | * edge of the current clock cycle, while the "in" side |
| 132 | * captures the data on (or shortly after) the trailing edge of |
| 133 | * the clock cycle. |
| 134 | * bit 1: CPOL, determines the polarity of the clock. CPOL=0 is a |
| 135 | * clock which idles at 0, and each cycle consists of a pulse |
| 136 | * of 1. CPOL=1 is a clock which idles at 1, and each cycle |
| 137 | * consists of a pulse of 0. |
| 138 | * bit 2: CS_HIGH, if 1, chip select active high, else active low. |
| 139 | * bit 3: LSB_FIRST, determines per-word bits-on-wire, if 0, MSB |
| 140 | * first, else LSB first. |
| 141 | * bit 4: LOOP, loopback mode. |
| 142 | * @freq: the transfer speed in Hz. |
| 143 | * @word_delay_ns: delay to be inserted between consecutive words of a |
| 144 | * transfer, in ns unit. |
| 145 | * @cs_setup_ns: delay to be introduced after CS is asserted, in ns |
| 146 | * unit. |
| 147 | * @cs_delay_hold_ns: delay to be introduced before CS is deasserted |
| 148 | * for each transfer, in ns unit. |
| 149 | * @cs_change_delay_inactive_ns: delay to be introduced after CS is |
| 150 | * deasserted and before next asserted, in ns unit. |
| 151 | */ |
| 152 | struct spi_transfer_head { |
| 153 | uint8_t chip_select_id; |
| 154 | uint8_t bits_per_word; |
| 155 | uint8_t cs_change; |
| 156 | uint8_t tx_nbits; |
| 157 | uint8_t rx_nbits; |
| 158 | uint8_t reserved[3]; |
| 159 | uint32_t mode; |
| 160 | uint32_t freq; |
| 161 | uint32_t word_delay_ns; |
| 162 | uint32_t cs_setup_ns; |
| 163 | uint32_t cs_delay_hold_ns; |
| 164 | uint32_t cs_change_delay_inactive_ns; |
| 165 | }; |
| 166 | |
| 167 | /** |
| 168 | * struct spi_transfer_result - virtio SPI transfer result |
| 169 | * @result: Transfer result code. |
| 170 | * VIRTIO_SPI_TRANS_OK: Transfer successful. |
| 171 | * VIRTIO_SPI_PARAM_ERR: Parameter error. |
| 172 | * VIRTIO_SPI_TRANS_ERR: Transfer error. |
| 173 | */ |
| 174 | struct spi_transfer_result { |
| 175 | #define VIRTIO_SPI_TRANS_OK 0 |
| 176 | #define VIRTIO_SPI_PARAM_ERR 1 |
| 177 | #define VIRTIO_SPI_TRANS_ERR 2 |
| 178 | uint8_t result; |
| 179 | }; |
| 180 | |
| 181 | #endif /* #ifndef _LINUX_VIRTIO_VIRTIO_SPI_H */ |