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 <lk/compiler.h> 20 #include <stdbool.h> 21 #include <stdint.h> 22 #include <sys/types.h> 23 24 __BEGIN_CDECLS 25 26 /** 27 * DOC: API notes 28 * 29 * This module defines an API for implementing hardware-specific SPI controller 30 * driver. It is expected that it will be working in conjunction with higher 31 * level service that will make calls described here. 32 */ 33 34 /** 35 * struct spi_dev_ctx - opaque SPI device context structure 36 * 37 * This is an opaque implementation-specific SPI device context structure. It is 38 * passed around to indicate active SPI device. This device context structure 39 * must uniquely identify SPI device, physical SPI bus it is connected to, and 40 * hardware configuration parameters required to talk to the above device. 41 * 42 * &struct spi_dev_ctx must be allocated by the SPI driver and provided to SPI 43 * service via add_spi_service() API as port-specific private data in @priv 44 * field of &struct tipc_port. 45 * 46 * Multiple SPI devices might be connected to the same physical SPI bus. Only 47 * one device can be active at a time. Only one client can be connected to a 48 * device at a time. 49 * 50 * spi_seq_*() routines are used to report to SPI device when a sequence of SPI 51 * requests begins/ends. spi_req_*() routines are used to invoke individual SPI 52 * requests. SPI device driver implementation may choose one of these options: 53 * - execute SPI requests as soon as corresponding spi_req_*() routine is 54 * called 55 * - rely on spi_seq_*() to batch together SPI requests 56 * SPI requests must either all be batched or all be executed individually. 57 */ 58 struct spi_dev_ctx; 59 60 /** 61 * spi_is_bus_shared() - check if specified SPI device shares the SPI bus with 62 * other devices. 63 * @dev: SPI device to query 64 * 65 * If the SPI bus is shared, spi_seq_abort() will be called instead of 66 * spi_seq_commit() for a sequence that would leave CS asserted. 67 * 68 * Return: true if SPI bus is shared, false otherwise 69 */ 70 bool spi_is_bus_shared(struct spi_dev_ctx* dev); 71 72 /** 73 * spi_req_set_clk() - set SPI clock speed for specified SPI device 74 * @dev: SPI device to configure 75 * @clk_hz: pointer to SPI clock speed, in Hz 76 * 77 * Called by SPI library to set SPI clock speed. Upon successful setting of the 78 * clock, or after calculating what that clock rate will be, @clk_hz is expected 79 * to point to the real clock speed that the device was configured to. That 80 * real clock speed must be equal or less than requested clock speed. 81 * 82 * SPI driver should set the value of @clk_hz using WRITE_ONCE() macro. 83 * 84 * SPI driver implementation may choose to either (1) execute the request 85 * immediately or (2) place the request in a batch that will later be committed 86 * by spi_seq_commit(). 87 * 88 * Return: 0 on success, or negative error code otherwise. 89 */ 90 int spi_req_set_clk(struct spi_dev_ctx* dev, uint64_t* clk_hz); 91 92 /** 93 * spi_req_cs_assert() - assert chip select (CS) for specified SPI device 94 * @dev: SPI device to assert CS for 95 * 96 * Called by SPI library to assert CS and start a SPI transaction. A SPI 97 * transaction is defined as a series of transfers with asserted CS. While SPI 98 * transaction is active no other transaction can become active on the same 99 * physical SPI bus. These transactions must remain active until CS is 100 * deasserted and SPI transaction is stopped for the same device. 101 * 102 * Activating a SPI device already in active transaction state must result in an 103 * error. 104 * 105 * SPI driver implementation may choose to either (1) execute the request 106 * immediately or (2) place the request in a batch that will later be committed 107 * by spi_seq_commit(). 108 * 109 * Return: 0 on success, or negative error code otherwise 110 */ 111 int spi_req_cs_assert(struct spi_dev_ctx* dev); 112 113 /** 114 * spi_req_cs_deassert() - deassert chip select (CS) for specified SPI device 115 * @dev: SPI device to deassert CS for 116 * 117 * Called by SPI library to deassert CS and stop ongoing SPI transaction. 118 * 119 * Stopping SPI transaction for a device that is not currently in active 120 * transaction state must result in an error. 121 * 122 * SPI driver implementation may choose to either (1) execute the request 123 * immediately or (2) place the request in a batch that will later be committed 124 * by spi_seq_commit(). 125 * 126 * Return: 0 on success, negative error code otherwise 127 */ 128 int spi_req_cs_deassert(struct spi_dev_ctx* dev); 129 130 /** 131 * spi_req_xfer() - send/receive an array of bytes in device-specific bit order 132 * @dev: device to talk to which must be in active transaction state. 133 * @tx: points to array of bytes to send over SPI bus. This parameter could be 134 * NULL to indicate that there are no bytes to send. 135 * @rx: points to memory buffer to store bytes received from device. This 136 * parameter could be NULL to indicate that all received bytes should be 137 * discarded. 138 * @len: number of bytes to transmit. It could be 0. 139 * 140 * Called by SPI library to send/receive data consisting of specified array of 141 * bytes in device-specific on wire bit order. Either or both @rx and @tx could 142 * be NULL. Both @tx and @rx could point to the same memory location. 143 * 144 * @len also controls the number of clock cycles sent the SPI bus. If the 145 * word-size is a multiple of 8 bits, the number of SPI clock cycles should be 146 * round_up(@len * 8, word-size). Otherwise, details TBD. 147 * 148 * SPI driver implementation may choose to either (1) execute the request 149 * immediately or (2) place the request in a batch that will later be committed 150 * by spi_seq_commit(). 151 * 152 * Return: 0 on success, negative error code otherwise 153 */ 154 int spi_req_xfer(struct spi_dev_ctx* dev, void* tx, void* rx, size_t len); 155 156 /** 157 * spi_req_delay() - delay remaining SPI requests for specified SPI device 158 * @dev: SPI device to configure 159 * @delay_ns: amount of time to delay remaining SPI requests by, in ns 160 * 161 * Called by SPI library to insert a delay between SPI requests. 162 * 163 * This command is expected to produce delay times as close as possible to 164 * @delay_ns on a best-effort basis. Actual delay time must be larger than 165 * @delay_ns. If a SPI sequence fails due to unsatisfied timing requirements, 166 * clients may retry. 167 * 168 * SPI driver implementation may choose to either (1) execute the request 169 * immediately or (2) place the request in a batch that will later be committed 170 * by spi_seq_commit(). 171 * 172 * Return: 0 on success, or negative error code otherwise. 173 */ 174 int spi_req_delay(struct spi_dev_ctx* dev, uint64_t delay_ns); 175 176 /** 177 * spi_seq_begin() - begin a sequence of SPI requests for specified SPI device 178 * @dev: SPI device to begin sequence of commands for 179 * @num_cmds: number of SPI commands the upcoming sequence 180 * 181 * Called by SPI library to begin a sequence of SPI requests. 182 * 183 * Return: 0 on success, negative error code otherwise 184 */ 185 int spi_seq_begin(struct spi_dev_ctx* dev, size_t num_cmds); 186 187 /** 188 * spi_seq_commit() - commit a sequence of SPI requests for specified SPI device 189 * @dev: SPI device to commit sequence of commands for 190 * 191 * Called by SPI library to commit a sequence of SPI requests. SPI driver 192 * implementations that batch SPI requests must execute the batch at this point. 193 * 194 * Return: 0 if all command were successful, negative error code otherwise 195 */ 196 int spi_seq_commit(struct spi_dev_ctx* dev); 197 198 /** 199 * spi_seq_abort() - abort a sequence of SPI requests in progress 200 * @dev: SPI device to abort sequence of commands for 201 * 202 * Called by SPI library to abort a sequence of SPI requests. This routine must 203 * restore the state of CS to the state before the sequence has begun. 204 */ 205 void spi_seq_abort(struct spi_dev_ctx* dev); 206 207 __END_CDECLS 208