virtio_spi.h

  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 <linux/types.h>
 10#include <linux/virtio_config.h>
 11#include <linux/virtio_ids.h>
 12#include <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 */
 80struct virtio_spi_config {
 81	__u8 cs_max_number;
 82	__u8 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	__u8 tx_nbits_supported;
 87	__u8 rx_nbits_supported;
 88	__le32 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	__le32 mode_func_supported;
 97	__le32 max_freq_hz;
 98	__le32 max_word_delay_ns;
 99	__le32 max_cs_setup_ns;
100	__le32 max_cs_hold_ns;
101	__le32 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 */
152struct spi_transfer_head {
153	__u8 chip_select_id;
154	__u8 bits_per_word;
155	__u8 cs_change;
156	__u8 tx_nbits;
157	__u8 rx_nbits;
158	__u8 reserved[3];
159	__le32 mode;
160	__le32 freq;
161	__le32 word_delay_ns;
162	__le32 cs_setup_ns;
163	__le32 cs_delay_hold_ns;
164	__le32 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 */
174struct 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	__u8 result;
179};
180
181#endif /* #ifndef _LINUX_VIRTIO_VIRTIO_SPI_H */