1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <assert.h> 20 #include <lk/compiler.h> 21 #include <stdint.h> 22 23 __BEGIN_CDECLS 24 25 /* Alignment for structures sent to SPI server via shared memory */ 26 #define SPI_CMD_SHM_ALIGN 8 27 28 /** 29 * enum spi_srv_err - collection of error codes returned by SPI server 30 * @SPI_SRV_NO_ERROR: all OK 31 * @SPI_SRV_ERR_GENERIC: unknown error. Can occur when there's an 32 * internal server error 33 * @SPI_SRV_ERR_INVALID_ARGS: invalid arguments in the request 34 * @SPI_SRV_ERR_NOT_SUPPORTED: command operation not supported in the 35 * request 36 * @SPI_SRV_ERR_NOT_IMPLEMENTED: requested command not implemented 37 * @SPI_SRV_ERR_BUSY: pending request for this channel 38 * @SPI_SRV_ERR_TOO_BIG: not enough space to handle request 39 */ 40 enum spi_srv_err { 41 SPI_SRV_NO_ERROR = 0, 42 SPI_SRV_ERR_GENERIC, 43 SPI_SRV_ERR_INVALID_ARGS, 44 SPI_SRV_ERR_NOT_SUPPORTED, 45 SPI_SRV_ERR_NOT_IMPLEMENTED, 46 SPI_SRV_ERR_BUSY, 47 SPI_SRV_ERR_TOO_BIG, 48 }; 49 50 /** 51 * enum spi_cmd_common - common command identifiers for SPI operations 52 * @SPI_CMD_RESP_BIT_SHIFT: response bit shift 53 * @SPI_CMD_RESP_BIT: response bit set as part of response 54 * @SPI_CMD_OP_SHIFT: operation bit shift 55 * @SPI_CMD_OP_MASK: operation mask bit 56 */ 57 enum spi_cmd_common { 58 SPI_CMD_RESP_BIT_SHIFT = 0, 59 SPI_CMD_RESP_BIT = (0x1u << SPI_CMD_RESP_BIT_SHIFT), 60 SPI_CMD_OP_SHIFT = 1, 61 SPI_CMD_OP_MASK = (0x7Fu << SPI_CMD_OP_SHIFT), 62 }; 63 64 /** 65 * enum spi_cmd_msg - command identifiers for operations sent as TIPC messages 66 * @SPI_CMD_MSG_OP_SHM_MAP: operation code for mapping shared memory 67 * @SPI_CMD_MSG_OP_BATCH_EXEC: operation code for execution of a batch of 68 * commands 69 */ 70 enum spi_cmd_msg { 71 SPI_CMD_MSG_OP_SHM_MAP = (0x1u << SPI_CMD_OP_SHIFT), 72 SPI_CMD_MSG_OP_BATCH_EXEC = (0x2u << SPI_CMD_OP_SHIFT), 73 }; 74 75 /** 76 * enum spi_cmd_shm - command identifiers for operations sent in shared memory 77 * @SPI_CMD_SHM_OP_XFER: operation code for data transfer 78 * @SPI_CMD_SHM_OP_CS_ASSERT: operation code for chip select assert 79 * @SPI_CMD_SHM_OP_CS_DEASSERT: operation code for chip select deassert 80 * @SPI_CMD_SHM_OP_SET_CLK: operation code for setting SPI clock 81 * @SPI_CMD_SHM_OP_DELAY: operation code for delays between commands 82 */ 83 enum spi_cmd_shm { 84 SPI_CMD_SHM_OP_XFER = (0x1u << SPI_CMD_OP_SHIFT), 85 SPI_CMD_SHM_OP_CS_ASSERT = (0x2u << SPI_CMD_OP_SHIFT), 86 SPI_CMD_SHM_OP_CS_DEASSERT = (0x3u << SPI_CMD_OP_SHIFT), 87 SPI_CMD_SHM_OP_SET_CLK = (0x4u << SPI_CMD_OP_SHIFT), 88 SPI_CMD_SHM_OP_DELAY = (0x5u << SPI_CMD_OP_SHIFT), 89 }; 90 91 /** 92 * enum spi_xfer_flags - flag identifiers for data xfer operation 93 * @SPI_XFER_FLAGS_TX: flag to indicate transmitting data 94 * @SPI_XFER_FLAGS_RX: flag to indicate receiving data 95 */ 96 enum spi_xfer_flags { 97 SPI_XFER_FLAGS_TX = (0x1u << 0), 98 SPI_XFER_FLAGS_RX = (0x1u << 1), 99 }; 100 101 /** 102 * struct spi_msg_req - SPI request header for TIPC messages 103 * @cmd: command identifier - one of &enum spi_cmd_msg 104 */ 105 struct spi_msg_req { 106 uint32_t cmd; 107 }; 108 109 /** 110 * struct spi_msg_resp - SPI response header for TIPC messages 111 * @cmd: command identifier - %SPI_CMD_RESP_BIT or'ed with a cmd in 112 * one of &enum spi_cmd_msg 113 * @status: response status of the SPI operation 114 */ 115 struct spi_msg_resp { 116 uint32_t cmd; 117 uint32_t status; 118 }; 119 120 /** 121 * struct spi_shm_hdr - SPI header for commands in shared memory 122 * @cmd: command identifier. Requests contain one of &enum spi_cmd_shm. 123 * Server responses contain one of &enum spi_cmd_shm or'ed with 124 * %SPI_CMD_RESP_BIT. 125 * @status: response status of the SPI operation 126 */ 127 struct spi_shm_hdr { 128 uint32_t cmd; 129 uint32_t status; 130 }; 131 132 /** 133 * struct spi_shm_map_req - arguments for %SPI_CMD_MSG_OP_SHM_MAP request 134 * @len: length of shared memory region in bytes, must be page-aligned 135 */ 136 struct spi_shm_map_req { 137 uint32_t len; 138 }; 139 140 /** 141 * struct spi_batch_req - arguments for %SPI_CMD_MSG_OP_BATCH_EXEC request 142 * @len: total length of SPI requests, arguments, and data 143 * @num_cmds: number of commands in the batch 144 */ 145 struct spi_batch_req { 146 uint32_t len; 147 uint32_t num_cmds; 148 }; 149 150 /** 151 * struct spi_batch_resp - arguments for %SPI_CMD_MSG_OP_BATCH_EXEC response 152 * @len: total length of SPI responses, arguments, and data 153 * @failed: index of failed command if an error occurred 154 */ 155 struct spi_batch_resp { 156 uint32_t len; 157 uint32_t failed; 158 }; 159 160 /** 161 * struct spi_xfer_args - arguments for %SPI_CMD_SHM_OP_XFER request and 162 * response 163 * @len: data length in bytes 164 * @flags: configuration flags - see &enum spi_xfer_flags 165 * 166 * @len bytes of data is allocated directly after &struct spi_xfer_args in 167 * shared memory. TX and RX buffers, configured by @flags, are always set to use 168 * that data (i.e. they may point to the same location). If neither TX nor RX 169 * are configured, data is still allocated, but not used. 170 * 171 * @len also controls the number of clock cycles sent the SPI bus. If the 172 * word-size is a multiple of 8 bits, the number of SPI clock cycles are 173 * round_up(@len * 8, word-size). Otherwise, details TBD. 174 */ 175 struct spi_xfer_args { 176 uint32_t len; 177 uint32_t flags; 178 }; 179 180 /** 181 * struct spi_clk_args - arguments for %SPI_CMD_SHM_OP_CLK request and response 182 * @clk_hz: SPI clock speed, in Hz. Request contains clock speed requested by 183 * the client. Response contains actual clock speed that was set. 184 */ 185 struct spi_clk_args { 186 uint64_t clk_hz; 187 }; 188 189 /** 190 * struct spi_clk_args - arguments for %SPI_CMD_SHM_OP_DELAY request and 191 * response 192 * @delay_ns: delay, in ns. Request contains amount of delay time requested by 193 * the client. Response must be zero. 194 */ 195 struct spi_delay_args { 196 uint64_t delay_ns; 197 }; 198 __END_CDECLS 199