Line data Source code
1 1 : /*
2 : * Copyright (c) 2015 Intel Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup spi_interface
10 : * @brief Main header file for SPI (Serial Peripheral Interface) driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_SPI_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_SPI_H_
15 :
16 : /**
17 : * @brief Interfaces for Serial Peripheral Interface (SPI)
18 : * controllers.
19 : * @defgroup spi_interface SPI
20 : * @since 1.0
21 : * @version 1.0.0
22 : * @ingroup io_interfaces
23 : * @{
24 : */
25 :
26 : #include <zephyr/types.h>
27 : #include <stddef.h>
28 : #include <zephyr/device.h>
29 : #include <zephyr/dt-bindings/spi/spi.h>
30 : #include <zephyr/drivers/gpio.h>
31 : #include <zephyr/kernel.h>
32 : #include <zephyr/sys/__assert.h>
33 : #include <zephyr/rtio/rtio.h>
34 : #include <zephyr/stats/stats.h>
35 :
36 : #ifdef __cplusplus
37 : extern "C" {
38 : #endif
39 :
40 : /**
41 : * @name SPI operational mode
42 : * @{
43 : */
44 :
45 : /**
46 : * @brief Master (controller) mode.
47 : *
48 : * In this case the device used with the API will function as a controller,
49 : * meaning it will control the CLK line on the SPI bus and the chip select,
50 : * and therefore have full control over the timing of the transaction.
51 : */
52 1 : #define SPI_OP_MODE_MASTER 0U
53 :
54 : /**
55 : * @brief Slave (peripheral) mode.
56 : *
57 : * With this mode, the device will function as a peripheral,
58 : * meaning it will need to wait for it's select line to be asserted,
59 : * and will be need to be subject to pacing by a controller's clock in order to
60 : * send and receive data during a transaction.
61 : */
62 1 : #define SPI_OP_MODE_SLAVE BIT(0) /**< Slave mode. */
63 :
64 : /** @cond INTERNAL_HIDDEN */
65 : #define SPI_OP_MODE_MASK 0x1U
66 : /** @endcond */
67 :
68 : /**
69 : * @brief Get SPI Operational mode bitmask from a @ref spi_operation_t
70 : */
71 1 : #define SPI_OP_MODE_GET(_operation_) ((_operation_) & SPI_OP_MODE_MASK)
72 : /** @} */
73 :
74 :
75 : /**
76 : * @name SPI Clock Modes
77 : * @{
78 : */
79 :
80 : /**
81 : * @brief Clock Polarity (Clock Idle State)
82 : *
83 : * @details
84 : * Used in @ref spi_operation_t definition.
85 : * If set, clock idle state will be 1 and active state will be 0.
86 : * If unset, clock idle state will be 0 and active state will be 1.
87 : * Unset is the default.
88 : */
89 1 : #define SPI_MODE_CPOL BIT(1)
90 :
91 : /**
92 : * @brief Clock Phase (Clock data capture edge)
93 : *
94 : * @details
95 : * Used in @ref spi_operation_t definition.
96 : * If set, data is captured on transition from active to idle CLK state.
97 : * If unset, data is captured on transition from idle to active state.
98 : * Unset is the default.
99 : */
100 1 : #define SPI_MODE_CPHA BIT(2)
101 :
102 : /**
103 : * @brief Controller loopback mode
104 : *
105 : * @details
106 : * For testing purposes, enable hardware loopback,
107 : * which means that transmit data is fed back to the receiver of the same controller.
108 : *
109 : * Not all controllers support this feature.
110 : */
111 1 : #define SPI_MODE_LOOP BIT(3)
112 :
113 : /** @cond INTERNAL_HIDDEN */
114 : #define SPI_MODE_MASK (0xEU)
115 : /** @endcond */
116 :
117 : /**
118 : * @brief Get SPI clock polarity and phase mode bitmask from a @ref spi_operation_t
119 : */
120 1 : #define SPI_MODE_GET(_mode_) \
121 : ((_mode_) & SPI_MODE_MASK)
122 :
123 : /** @} */
124 :
125 :
126 : /**
127 : * @name SPI Data Word Configurations
128 : *
129 : * A SPI Data word is a value that is shifted in/out of the controller's hardware FIFO
130 : * and is the atomic unit of communication on the spi bus.
131 : * A word is also called a "data frame" in this API.
132 : * A transfer is made up of an arbitrary number of words.
133 : * The following options specify configurations of the SPI word for the operation.
134 : *
135 : * @{
136 : */
137 :
138 : /** Words are most significant bit first, used for @ref spi_operation_t */
139 1 : #define SPI_TRANSFER_MSB (0U)
140 : /** Words are least significant bit first, used for @ref spi_operation_t */
141 1 : #define SPI_TRANSFER_LSB BIT(4)
142 :
143 : /** @cond INTERNAL_HIDDEN */
144 : #define SPI_WORD_SIZE_SHIFT (5U)
145 : #define SPI_WORD_SIZE_MASK (0x3FU << SPI_WORD_SIZE_SHIFT)
146 : /** @endcond */
147 :
148 : /**
149 : * @brief Get SPI word size in bits from a @ref spi_operation_t
150 : *
151 : * @param operation A @ref spi_operation_t from which to get the configured word size.
152 : * @retval The size (in bits) of a spi word for the operation.
153 : */
154 1 : #define SPI_WORD_SIZE_GET(operation) \
155 : (((operation) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)
156 :
157 : /**
158 : * @brief Get a bitmask to set the word size in a @ref spi_operation_t
159 : *
160 : * @param word_size The size of a SPI data frame in bits.
161 : * @retval A bitmask to apply to a @ref spi_operation_t
162 : */
163 1 : #define SPI_WORD_SET(word_size) \
164 : ((word_size) << SPI_WORD_SIZE_SHIFT)
165 :
166 : /** @} */
167 :
168 :
169 : /**
170 : * @name SPI Transfer control flags
171 : * @{
172 : */
173 :
174 : /**
175 : * @brief Keep chip select active after transaction
176 : *
177 : * After one of the spi transceive calls described in this API,
178 : * if this flag is set in the spi config operation, then
179 : * attempt to keep the CS active after the call, if supported and possible.
180 : */
181 1 : #define SPI_HOLD_ON_CS BIT(12)
182 :
183 : /**
184 : * @brief Retain ownership of the spi device
185 : *
186 : * This is a software control parameter that will prevent the spi device
187 : * from being accessed by other API callers after the transaction,
188 : * and therefore should be used with caution.
189 : *
190 : * The identifying piece of information for who "locks" the device
191 : * is the spi_config pointer given to the transaction API, so this same
192 : * config should be re-used to do another transaction or release the lock.
193 : *
194 : * See @ref spi_release for how to release the lock.
195 : */
196 1 : #define SPI_LOCK_ON BIT(13)
197 :
198 : /**
199 : * @brief Chip select active state configuration
200 : *
201 : * If this flag is set, the CS will be active high.
202 : * If this flag is unset, the CS will be active low.
203 : *
204 : * Default is active low (unset) as that is most common for spi peripherals.
205 : *
206 : * Not all controllers are able to handle this natively, in which case a
207 : * gpio can still be used to control the CS through software with a @ref spi_cs_control
208 : */
209 1 : #define SPI_CS_ACTIVE_HIGH BIT(14)
210 :
211 : /** @} */
212 :
213 :
214 : /**
215 : * @name SPI MISO lines
216 : * @{
217 : *
218 : * Some controllers support dual, quad or octal MISO lines connected to slaves.
219 : * Default is single, which is the case most of the time.
220 : * Without @kconfig{CONFIG_SPI_EXTENDED_MODES} being enabled, single is the
221 : * only supported one.
222 : */
223 1 : #define SPI_LINES_SINGLE (0U << 16) /**< Single line */
224 1 : #define SPI_LINES_DUAL (1U << 16) /**< Dual lines */
225 1 : #define SPI_LINES_QUAD (2U << 16) /**< Quad lines */
226 1 : #define SPI_LINES_OCTAL (3U << 16) /**< Octal lines */
227 :
228 1 : #define SPI_LINES_MASK (0x3U << 16) /**< Mask for MISO lines in spi_operation_t */
229 :
230 : /** @} */
231 :
232 : /**
233 : * @name SPI GPIO Chip Select control
234 : * @{
235 : */
236 :
237 : /**
238 : * @brief SPI Chip Select control structure
239 : *
240 : * This can be used to control a CS line via a GPIO line, instead of
241 : * using the controller internal CS logic.
242 : *
243 : */
244 1 : struct spi_cs_control {
245 : /**
246 : * GPIO devicetree specification of CS GPIO.
247 : * The device pointer can be set to NULL to fully inhibit CS control if
248 : * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
249 : * equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct
250 : * spi_config.
251 : */
252 1 : struct gpio_dt_spec gpio;
253 : /**
254 : * Delay in microseconds to wait before starting the
255 : * transmission and before releasing the CS line.
256 : */
257 1 : uint32_t delay;
258 : };
259 :
260 : /**
261 : * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
262 : *
263 : * Example devicetree fragment:
264 : *
265 : * @code{.devicetree}
266 : * gpio1: gpio@abcd0001 { ... };
267 : *
268 : * gpio2: gpio@abcd0002 { ... };
269 : *
270 : * spi@abcd0003 {
271 : * compatible = "vnd,spi";
272 : * cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
273 : * <&gpio2 20 GPIO_ACTIVE_LOW>;
274 : *
275 : * a: spi-dev-a@0 {
276 : * reg = <0>;
277 : * };
278 : *
279 : * b: spi-dev-b@1 {
280 : * reg = <1>;
281 : * };
282 : * };
283 : * @endcode
284 : *
285 : * Example usage:
286 : *
287 : * @code{.c}
288 : * SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(a)) \
289 : * // { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
290 : * SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(b)) \
291 : * // { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }
292 : * @endcode
293 : *
294 : * @param spi_dev a SPI device node identifier
295 : * @return #gpio_dt_spec struct corresponding with spi_dev's chip select
296 : */
297 1 : #define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev) \
298 : GPIO_DT_SPEC_GET_BY_IDX_OR(DT_BUS(spi_dev), cs_gpios, \
299 : DT_REG_ADDR_RAW(spi_dev), {})
300 :
301 : /**
302 : * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
303 : *
304 : * This is equivalent to
305 : * <tt>SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))</tt>.
306 : *
307 : * @param inst Devicetree instance number
308 : * @return #gpio_dt_spec struct corresponding with spi_dev's chip select
309 : */
310 1 : #define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
311 : SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))
312 :
313 : /**
314 : * @brief Initialize and get a pointer to a @p spi_cs_control from a
315 : * devicetree node identifier
316 : *
317 : * This helper is useful for initializing a device on a SPI bus. It
318 : * initializes a struct spi_cs_control and returns a pointer to it.
319 : * Here, @p node_id is a node identifier for a SPI device, not a SPI
320 : * controller.
321 : *
322 : * Example devicetree fragment:
323 : *
324 : * @code{.devicetree}
325 : * spi@abcd0001 {
326 : * cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
327 : * spidev: spi-device@0 { ... };
328 : * };
329 : * @endcode
330 : *
331 : * Example usage:
332 : *
333 : * @code{.c}
334 : * struct spi_cs_control ctrl =
335 : * SPI_CS_CONTROL_INIT(DT_NODELABEL(spidev), 2);
336 : * @endcode
337 : *
338 : * This example is equivalent to:
339 : *
340 : * @code{.c}
341 : * struct spi_cs_control ctrl = {
342 : * .gpio = SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(spidev)),
343 : * .delay = 2,
344 : * };
345 : * @endcode
346 : *
347 : * @param node_id Devicetree node identifier for a device on a SPI bus
348 : * @param delay_ The @p delay field to set in the @p spi_cs_control
349 : * @return a pointer to the @p spi_cs_control structure
350 : */
351 1 : #define SPI_CS_CONTROL_INIT(node_id, delay_) \
352 : { \
353 : .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id), \
354 : .delay = (delay_), \
355 : }
356 :
357 : /**
358 : * @brief Get a pointer to a @p spi_cs_control from a devicetree node
359 : *
360 : * This is equivalent to
361 : * <tt>SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay)</tt>.
362 : *
363 : * Therefore, @p DT_DRV_COMPAT must already be defined before using
364 : * this macro.
365 : *
366 : * @param inst Devicetree node instance number
367 : * @param delay_ The @p delay field to set in the @p spi_cs_control
368 : * @return a pointer to the @p spi_cs_control structure
369 : */
370 1 : #define SPI_CS_CONTROL_INIT_INST(inst, delay_) \
371 : SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)
372 :
373 : /** @} */
374 :
375 : /**
376 : * @typedef spi_operation_t
377 : * Opaque type to hold the SPI operation flags.
378 : */
379 : #if defined(CONFIG_SPI_EXTENDED_MODES)
380 : typedef uint32_t spi_operation_t;
381 : #else
382 1 : typedef uint16_t spi_operation_t;
383 : #endif
384 :
385 : /**
386 : * @brief SPI controller configuration structure
387 : *
388 : * @warning Most drivers use pointer comparison to determine whether a passed
389 : * configuration is different from one used in a previous transaction.
390 : * Changes to fields in the structure may not be detected.
391 : */
392 1 : struct spi_config {
393 : /** @brief Bus frequency in Hertz. */
394 1 : uint32_t frequency;
395 : /**
396 : * @brief Operation flags.
397 : *
398 : * It is a bit field with the following parts:
399 : *
400 : * - 0: Master or slave.
401 : * - 1..3: Clock polarity, phase and loop mode.
402 : * - 4: LSB or MSB first.
403 : * - 5..10: Size of a data frame (word) in bits.
404 : * - 11: Full/half duplex.
405 : * - 12: Hold on the CS line if possible.
406 : * - 13: Keep resource locked for the caller.
407 : * - 14: Active high CS logic.
408 : * - 15: Motorola or TI frame format (optional).
409 : *
410 : * If @kconfig{CONFIG_SPI_EXTENDED_MODES} is enabled:
411 : *
412 : * - 16..17: MISO lines (Single/Dual/Quad/Octal).
413 : * - 18..31: Reserved for future use.
414 : */
415 1 : spi_operation_t operation;
416 : /** @brief Slave number from 0 to host controller slave limit. */
417 1 : uint16_t slave;
418 : /**
419 : * @brief GPIO chip-select line (optional, must be initialized to zero
420 : * if not used).
421 : */
422 1 : struct spi_cs_control cs;
423 : };
424 :
425 : /**
426 : * @brief Structure initializer for spi_config from devicetree
427 : *
428 : * This helper macro expands to a static initializer for a <tt>struct
429 : * spi_config</tt> by reading the relevant @p frequency, @p slave, and
430 : * @p cs data from the devicetree.
431 : *
432 : * @param node_id Devicetree node identifier for the SPI device whose
433 : * struct spi_config to create an initializer for
434 : * @param operation_ the desired @p operation field in the struct spi_config
435 : * @param delay_ the desired @p delay field in the struct spi_config's
436 : * spi_cs_control, if there is one
437 : */
438 1 : #define SPI_CONFIG_DT(node_id, operation_, delay_) \
439 : { \
440 : .frequency = DT_PROP(node_id, spi_max_frequency), \
441 : .operation = (operation_) | \
442 : DT_PROP(node_id, duplex) | \
443 : DT_PROP(node_id, frame_format) | \
444 : COND_CODE_1(DT_PROP(node_id, spi_cpol), SPI_MODE_CPOL, (0)) | \
445 : COND_CODE_1(DT_PROP(node_id, spi_cpha), SPI_MODE_CPHA, (0)) | \
446 : COND_CODE_1(DT_PROP(node_id, spi_hold_cs), SPI_HOLD_ON_CS, (0)), \
447 : .slave = DT_REG_ADDR(node_id), \
448 : .cs = SPI_CS_CONTROL_INIT(node_id, delay_), \
449 : }
450 :
451 : /**
452 : * @brief Structure initializer for spi_config from devicetree instance
453 : *
454 : * This is equivalent to
455 : * <tt>SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)</tt>.
456 : *
457 : * @param inst Devicetree instance number
458 : * @param operation_ the desired @p operation field in the struct spi_config
459 : * @param delay_ the desired @p delay field in the struct spi_config's
460 : * spi_cs_control, if there is one
461 : */
462 1 : #define SPI_CONFIG_DT_INST(inst, operation_, delay_) \
463 : SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)
464 :
465 : /**
466 : * @brief Complete SPI DT information
467 : */
468 1 : struct spi_dt_spec {
469 : /** SPI bus */
470 1 : const struct device *bus;
471 : /** Slave specific configuration */
472 1 : struct spi_config config;
473 : };
474 :
475 : /**
476 : * @brief Structure initializer for spi_dt_spec from devicetree
477 : *
478 : * This helper macro expands to a static initializer for a <tt>struct
479 : * spi_dt_spec</tt> by reading the relevant bus, frequency, slave, and cs
480 : * data from the devicetree.
481 : *
482 : * Important: multiple fields are automatically constructed by this macro
483 : * which must be checked before use. @ref spi_is_ready_dt performs the required
484 : * @ref device_is_ready checks.
485 : *
486 : * @param node_id Devicetree node identifier for the SPI device whose
487 : * struct spi_dt_spec to create an initializer for
488 : * @param operation_ the desired @p operation field in the struct spi_config
489 : * @param delay_ the desired @p delay field in the struct spi_config's
490 : * spi_cs_control, if there is one
491 : */
492 1 : #define SPI_DT_SPEC_GET(node_id, operation_, delay_) \
493 : { \
494 : .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
495 : .config = SPI_CONFIG_DT(node_id, operation_, delay_) \
496 : }
497 :
498 : /**
499 : * @brief Structure initializer for spi_dt_spec from devicetree instance
500 : *
501 : * This is equivalent to
502 : * <tt>SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)</tt>.
503 : *
504 : * @param inst Devicetree instance number
505 : * @param operation_ the desired @p operation field in the struct spi_config
506 : * @param delay_ the desired @p delay field in the struct spi_config's
507 : * spi_cs_control, if there is one
508 : */
509 1 : #define SPI_DT_SPEC_INST_GET(inst, operation_, delay_) \
510 : SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)
511 :
512 : /**
513 : * @brief Value that will never compare true with any valid overrun character
514 : */
515 1 : #define SPI_MOSI_OVERRUN_UNKNOWN 0x100
516 :
517 : /**
518 : * @brief The value sent on MOSI when all TX bytes are sent, but RX continues
519 : *
520 : * For drivers where the MOSI line state when receiving is important, this value
521 : * can be queried at compile-time to determine whether allocating a constant
522 : * array is necessary.
523 : *
524 : * @param node_id Devicetree node identifier for the SPI device to query
525 : *
526 : * @retval SPI_MOSI_OVERRUN_UNKNOWN if controller does not export the value
527 : * @retval byte default MOSI value otherwise
528 : */
529 1 : #define SPI_MOSI_OVERRUN_DT(node_id) \
530 : DT_PROP_OR(node_id, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
531 :
532 : /**
533 : * @brief The value sent on MOSI when all TX bytes are sent, but RX continues
534 : *
535 : * This is equivalent to
536 : * <tt>SPI_MOSI_OVERRUN_DT(DT_DRV_INST(inst))</tt>.
537 : *
538 : * @param inst Devicetree instance number
539 : *
540 : * @retval SPI_MOSI_OVERRUN_UNKNOWN if controller does not export the value
541 : * @retval byte default MOSI value otherwise
542 : */
543 1 : #define SPI_MOSI_OVERRUN_DT_INST(inst) \
544 : DT_INST_PROP_OR(inst, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
545 :
546 : /**
547 : * @brief SPI buffer structure
548 : *
549 : * A SPI buffer describes either a real data buffer or an indication of NOP
550 : * For a NOP indicator:
551 : * If buffer is used for TX, only 0's will be sent for the length on the bus
552 : * If buffer is used for RX, that length of data received by bus will be ignored/skipped
553 : */
554 1 : struct spi_buf {
555 : /** Valid pointer to a data buffer, or NULL for NOP indication */
556 1 : void *buf;
557 : /** Length of the buffer @a buf in bytes, or length of NOP */
558 1 : size_t len;
559 : };
560 :
561 : /**
562 : * @brief SPI scatter-gather buffer array structure
563 : *
564 : * A spi_buf_set is a flexible description of a whole single SPI bus transfer.
565 : *
566 : * Since the set is an array of pointers to buffers, it means that pieces of a spi transfer
567 : * definition can be re-used across different transfers, without having to redefine or allocate
568 : * new memory for them each time.
569 : * This accomplishes what is called "scatter-gather" buffer management at the driver level with
570 : * user-provided buffers.
571 : */
572 1 : struct spi_buf_set {
573 : /** Pointer to an array of spi_buf, or NULL */
574 1 : const struct spi_buf *buffers;
575 : /** Number of buffers in the array pointed to: by @a buffers */
576 1 : size_t count;
577 : };
578 :
579 : /**
580 : * @name SPI Stats
581 : * @{
582 : */
583 : #if defined(CONFIG_SPI_STATS)
584 : STATS_SECT_START(spi)
585 : STATS_SECT_ENTRY32(rx_bytes)
586 : STATS_SECT_ENTRY32(tx_bytes)
587 : STATS_SECT_ENTRY32(transfer_error)
588 : STATS_SECT_END;
589 :
590 : STATS_NAME_START(spi)
591 : STATS_NAME(spi, rx_bytes)
592 : STATS_NAME(spi, tx_bytes)
593 : STATS_NAME(spi, transfer_error)
594 : STATS_NAME_END(spi);
595 :
596 : /**
597 : * @brief SPI specific device state which allows for SPI device class specific additions
598 : */
599 : struct spi_device_state {
600 : struct device_state devstate;
601 : struct stats_spi stats;
602 : };
603 :
604 : /**
605 : * @brief Get pointer to SPI statistics structure
606 : */
607 : #define Z_SPI_GET_STATS(dev_) \
608 : CONTAINER_OF(dev_->state, struct spi_device_state, devstate)->stats
609 :
610 : /**
611 : * @brief Increment the rx bytes for a SPI device
612 : *
613 : * @param dev_ Pointer to the device structure for the driver instance.
614 : */
615 : #define SPI_STATS_RX_BYTES_INCN(dev_, n) \
616 : STATS_INCN(Z_SPI_GET_STATS(dev_), rx_bytes, n)
617 :
618 : /**
619 : * @brief Increment the tx bytes for a SPI device
620 : *
621 : * @param dev_ Pointer to the device structure for the driver instance.
622 : */
623 : #define SPI_STATS_TX_BYTES_INCN(dev_, n) \
624 : STATS_INCN(Z_SPI_GET_STATS(dev_), tx_bytes, n)
625 :
626 : /**
627 : * @brief Increment the transfer error counter for a SPI device
628 : *
629 : * The transfer error count is incremented when there occurred a transfer error
630 : *
631 : * @param dev_ Pointer to the device structure for the driver instance.
632 : */
633 : #define SPI_STATS_TRANSFER_ERROR_INC(dev_) \
634 : STATS_INC(Z_SPI_GET_STATS(dev_), transfer_error)
635 :
636 : /** @cond INTERNAL_HIDDEN */
637 : /**
638 : * @brief Define a statically allocated and section assigned SPI device state
639 : */
640 : #define Z_SPI_DEVICE_STATE_DEFINE(dev_id) \
641 : static struct spi_device_state Z_DEVICE_STATE_NAME(dev_id) \
642 : __attribute__((__section__(".z_devstate")));
643 :
644 : /**
645 : * @brief Define an SPI device init wrapper function
646 : *
647 : * This does device instance specific initialization of common data (such as stats)
648 : * and calls the given init_fn
649 : */
650 : #define Z_SPI_INIT_FN(dev_id, init_fn) \
651 : static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
652 : { \
653 : struct spi_device_state *state = \
654 : CONTAINER_OF(dev->state, struct spi_device_state, devstate); \
655 : stats_init(&state->stats.s_hdr, STATS_SIZE_32, 3, \
656 : STATS_NAME_INIT_PARMS(spi)); \
657 : stats_register(dev->name, &(state->stats.s_hdr)); \
658 : return init_fn(dev); \
659 : }
660 : /** @endcond */
661 :
662 : #define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, \
663 : pm_device, data_ptr, cfg_ptr, \
664 : level, prio, api_ptr, ...) \
665 : Z_SPI_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
666 : Z_SPI_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
667 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
668 : DEVICE_DT_NAME(node_id), \
669 : &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
670 : deinit_fn, Z_DEVICE_DT_FLAGS(node_id), \
671 : pm_device, data_ptr, cfg_ptr, level, prio, \
672 : api_ptr, \
673 : &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
674 : __VA_ARGS__)
675 :
676 : static inline void spi_transceive_stats(const struct device *dev, int error,
677 : const struct spi_buf_set *tx_bufs,
678 : const struct spi_buf_set *rx_bufs)
679 : {
680 : uint32_t tx_bytes;
681 : uint32_t rx_bytes;
682 :
683 : if (error) {
684 : SPI_STATS_TRANSFER_ERROR_INC(dev);
685 : }
686 :
687 : if (tx_bufs) {
688 : tx_bytes = tx_bufs->count ? tx_bufs->buffers->len : 0;
689 : SPI_STATS_TX_BYTES_INCN(dev, tx_bytes);
690 : }
691 :
692 : if (rx_bufs) {
693 : rx_bytes = rx_bufs->count ? rx_bufs->buffers->len : 0;
694 : SPI_STATS_RX_BYTES_INCN(dev, rx_bytes);
695 : }
696 : }
697 : /** @} */
698 :
699 : #else /*CONFIG_SPI_STATS*/
700 :
701 : /**
702 : * @name SPI DT Device Macros
703 : * @{
704 : */
705 :
706 : /**
707 : * @brief Like DEVICE_DT_DEINIT_DEFINE() with SPI specifics.
708 : *
709 : * @details Defines a device which implements the SPI API. May
710 : * generate a custom device_state container struct and init_fn
711 : * wrapper when needed depending on SPI @kconfig{CONFIG_SPI_STATS}.
712 : *
713 : * @param node_id The devicetree node identifier.
714 : * @param init_fn Name of the init function of the driver.
715 : * @param deinit_fn Name of the deinit function of the driver.
716 : * @param pm PM device resources reference (NULL if device does not use PM).
717 : * @param data Pointer to the device's private data.
718 : * @param config The address to the structure containing the configuration
719 : * information for this instance of the driver.
720 : * @param level The initialization level. See SYS_INIT() for details.
721 : * @param prio Priority within the selected initialization level. See SYS_INIT()
722 : * for details.
723 : * @param api Provides an initial pointer to the API function struct used by
724 : * the driver. Can be NULL.
725 : */
726 : #define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, data, \
727 1 : config, level, prio, api, ...) \
728 : Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
729 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
730 : DEVICE_DT_NAME(node_id), init_fn, deinit_fn, \
731 : Z_DEVICE_DT_FLAGS(node_id), pm, data, config, \
732 : level, prio, api, \
733 : &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)), \
734 : __VA_ARGS__)
735 :
736 : /** @} */
737 :
738 0 : #define SPI_STATS_RX_BYTES_INC(dev_)
739 0 : #define SPI_STATS_TX_BYTES_INC(dev_)
740 0 : #define SPI_STATS_TRANSFER_ERROR_INC(dev_)
741 :
742 0 : #define spi_transceive_stats(dev, error, tx_bufs, rx_bufs)
743 :
744 : #endif /*CONFIG_SPI_STATS*/
745 :
746 : /**
747 : * @brief Like DEVICE_DT_DEINIT_DEFINE() without deinit function.
748 : *
749 : * @details Defines a device which implements the SPI API. May
750 : * generate a custom device_state container struct and init_fn
751 : * wrapper when needed depending on SPI @kconfig{CONFIG_SPI_STATS}.
752 : *
753 : * @param node_id The devicetree node identifier.
754 : * @param init_fn Name of the init function of the driver.
755 : * @param pm PM device resources reference (NULL if device does not use PM).
756 : * @param data Pointer to the device's private data.
757 : * @param config The address to the structure containing the configuration
758 : * information for this instance of the driver.
759 : * @param level The initialization level. See SYS_INIT() for details.
760 : * @param prio Priority within the selected initialization level. See SYS_INIT()
761 : * for details.
762 : * @param api Provides an initial pointer to the API function struct used by
763 : * the driver. Can be NULL.
764 : */
765 : #define SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, \
766 1 : api, ...) \
767 : SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, NULL, pm, data, config, \
768 : level, prio, api, __VA_ARGS__)
769 :
770 : /**
771 : * @brief Like SPI_DEVICE_DT_DEINIT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT`
772 : * compatible instead of a node identifier.
773 : *
774 : * @param inst Instance number. The `node_id` argument to SPI_DEVICE_DT_DEINIT_DEFINE() is
775 : * set to `DT_DRV_INST(inst)`.
776 : * @param ... Other parameters as expected by SPI_DEVICE_DT_DEFINE().
777 : */
778 1 : #define SPI_DEVICE_DT_INST_DEINIT_DEFINE(inst, ...) \
779 : SPI_DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
780 :
781 : /**
782 : * @brief Like SPI_DEVICE_DT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT`
783 : * compatible instead of a node identifier.
784 : *
785 : * @param inst Instance number. The `node_id` argument to SPI_DEVICE_DT_DEFINE() is
786 : * set to `DT_DRV_INST(inst)`.
787 : * @param ... Other parameters as expected by SPI_DEVICE_DT_DEFINE().
788 : */
789 1 : #define SPI_DEVICE_DT_INST_DEFINE(inst, ...) \
790 : SPI_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
791 :
792 : /**
793 : * @typedef spi_api_io
794 : * @brief Callback API for I/O
795 : * See spi_transceive() for argument descriptions
796 : */
797 1 : typedef int (*spi_api_io)(const struct device *dev,
798 : const struct spi_config *config,
799 : const struct spi_buf_set *tx_bufs,
800 : const struct spi_buf_set *rx_bufs);
801 :
802 : /**
803 : * @brief SPI callback for asynchronous transfer requests
804 : *
805 : * @param dev SPI device which is notifying of transfer completion or error
806 : * @param result Result code of the transfer request. 0 is success, -errno for failure.
807 : * @param data Transfer requester supplied data which is passed along to the callback.
808 : */
809 1 : typedef void (*spi_callback_t)(const struct device *dev, int result, void *data);
810 :
811 : /**
812 : * @typedef spi_api_io
813 : * @brief Callback API for asynchronous I/O
814 : * See spi_transceive_signal() for argument descriptions
815 : */
816 0 : typedef int (*spi_api_io_async)(const struct device *dev,
817 : const struct spi_config *config,
818 : const struct spi_buf_set *tx_bufs,
819 : const struct spi_buf_set *rx_bufs,
820 : spi_callback_t cb,
821 : void *userdata);
822 :
823 : #if defined(CONFIG_SPI_RTIO) || defined(DOXYGEN)
824 :
825 : /**
826 : * @typedef spi_api_iodev_submit
827 : * @brief Callback API for submitting work to a SPI device with RTIO
828 : */
829 : typedef void (*spi_api_iodev_submit)(const struct device *dev,
830 : struct rtio_iodev_sqe *iodev_sqe);
831 : #endif /* CONFIG_SPI_RTIO */
832 :
833 : /**
834 : * @typedef spi_api_release
835 : * @brief Callback API for unlocking SPI device.
836 : * See spi_release() for argument descriptions
837 : */
838 1 : typedef int (*spi_api_release)(const struct device *dev,
839 : const struct spi_config *config);
840 :
841 :
842 : /**
843 : * @brief SPI driver API
844 : * This is the mandatory API any SPI driver needs to expose.
845 : */
846 1 : __subsystem struct spi_driver_api {
847 0 : spi_api_io transceive;
848 : #ifdef CONFIG_SPI_ASYNC
849 : spi_api_io_async transceive_async;
850 : #endif /* CONFIG_SPI_ASYNC */
851 : #ifdef CONFIG_SPI_RTIO
852 : spi_api_iodev_submit iodev_submit;
853 : #endif /* CONFIG_SPI_RTIO */
854 0 : spi_api_release release;
855 : };
856 :
857 : /**
858 : * @brief Check if SPI CS is controlled using a GPIO.
859 : *
860 : * @param config SPI configuration.
861 : * @return true If CS is controlled using a GPIO.
862 : * @return false If CS is controlled by hardware or any other means.
863 : */
864 1 : static inline bool spi_cs_is_gpio(const struct spi_config *config)
865 : {
866 : return config->cs.gpio.port != NULL;
867 : }
868 :
869 : /**
870 : * @brief Check if SPI CS in @ref spi_dt_spec is controlled using a GPIO.
871 : *
872 : * @param spec SPI specification from devicetree.
873 : * @return true If CS is controlled using a GPIO.
874 : * @return false If CS is controlled by hardware or any other means.
875 : */
876 1 : static inline bool spi_cs_is_gpio_dt(const struct spi_dt_spec *spec)
877 : {
878 : return spi_cs_is_gpio(&spec->config);
879 : }
880 :
881 : /**
882 : * @brief Validate that SPI bus (and CS gpio if defined) is ready.
883 : *
884 : * @param spec SPI specification from devicetree
885 : *
886 : * @retval true if the SPI bus is ready for use.
887 : * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
888 : */
889 1 : static inline bool spi_is_ready_dt(const struct spi_dt_spec *spec)
890 : {
891 : /* Validate bus is ready */
892 : if (!device_is_ready(spec->bus)) {
893 : return false;
894 : }
895 : /* Validate CS gpio port is ready, if it is used */
896 : if (spi_cs_is_gpio_dt(spec) &&
897 : !gpio_is_ready_dt(&spec->config.cs.gpio)) {
898 : return false;
899 : }
900 : return true;
901 : }
902 :
903 : /**
904 : * @name SPI Synchronous Transfer Functions
905 : *
906 : * These functions will not return until transfer is complete
907 : *
908 : * @{
909 : */
910 :
911 : /**
912 : * @brief Read/write the specified amount of data from the SPI driver.
913 : *
914 : * @note This function is synchronous.
915 : *
916 : * @note In master mode, the chip select line will remain asserted (active) for
917 : * the entire duration of the transfer of all buffers in the provided buf sets.
918 : * Only after all buffers have been transferred will CS be deasserted.
919 : *
920 : * @note In peripheral mode, data transfer happens when the master asserts CS and
921 : * provides the clock. The function will wait for the master to complete
922 : * the transfer before returning. The CS is controlled by master
923 : * and therefore may not be continuously asserted for the whole transfer.
924 : *
925 : * @param dev Pointer to the device structure for the driver instance
926 : * @param config Pointer to a valid spi_config structure instance.
927 : * Pointer-comparison may be used to detect changes from
928 : * previous operations.
929 : * @param tx_bufs Buffer array where data to be sent originates from,
930 : * or NULL if none.
931 : * @param rx_bufs Buffer array where data to be read will be written to,
932 : * or NULL if none.
933 : *
934 : * @retval frames Positive number of frames received in slave mode.
935 : * @retval 0 If successful in master mode.
936 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
937 : * device hardware or the driver software.
938 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
939 : * @retval -errno Negative errno code on failure.
940 : */
941 1 : __syscall int spi_transceive(const struct device *dev,
942 : const struct spi_config *config,
943 : const struct spi_buf_set *tx_bufs,
944 : const struct spi_buf_set *rx_bufs);
945 :
946 : static inline int z_impl_spi_transceive(const struct device *dev,
947 : const struct spi_config *config,
948 : const struct spi_buf_set *tx_bufs,
949 : const struct spi_buf_set *rx_bufs)
950 : {
951 : const struct spi_driver_api *api =
952 : (const struct spi_driver_api *)dev->api;
953 : int ret;
954 :
955 : ret = api->transceive(dev, config, tx_bufs, rx_bufs);
956 : spi_transceive_stats(dev, ret, tx_bufs, rx_bufs);
957 :
958 : return ret;
959 : }
960 :
961 : /**
962 : * @brief Read/write data from an SPI bus specified in @p spi_dt_spec.
963 : *
964 : * This is equivalent to:
965 : *
966 : * spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
967 : *
968 : * @param spec SPI specification from devicetree
969 : * @param tx_bufs Buffer array where data to be sent originates from,
970 : * or NULL if none.
971 : * @param rx_bufs Buffer array where data to be read will be written to,
972 : * or NULL if none.
973 : *
974 : * @return a value from spi_transceive().
975 : */
976 1 : static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
977 : const struct spi_buf_set *tx_bufs,
978 : const struct spi_buf_set *rx_bufs)
979 : {
980 : return spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
981 : }
982 :
983 : /**
984 : * @brief Read the specified amount of data from the SPI driver.
985 : *
986 : * @note This function is synchronous.
987 : *
988 : * @note This function is a helper function calling spi_transceive.
989 : *
990 : * @param dev Pointer to the device structure for the driver instance
991 : * @param config Pointer to a valid spi_config structure instance.
992 : * Pointer-comparison may be used to detect changes from
993 : * previous operations.
994 : * @param rx_bufs Buffer array where data to be read will be written to.
995 : *
996 : * @retval frames Positive number of frames received in slave mode.
997 : * @retval 0 If successful.
998 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
999 : * device hardware or the driver software.
1000 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1001 : * @retval -errno Negative errno code on failure.
1002 : */
1003 1 : static inline int spi_read(const struct device *dev,
1004 : const struct spi_config *config,
1005 : const struct spi_buf_set *rx_bufs)
1006 : {
1007 : return spi_transceive(dev, config, NULL, rx_bufs);
1008 : }
1009 :
1010 : /**
1011 : * @brief Read data from a SPI bus specified in @p spi_dt_spec.
1012 : *
1013 : * This is equivalent to:
1014 : *
1015 : * spi_read(spec->bus, &spec->config, rx_bufs);
1016 : *
1017 : * @param spec SPI specification from devicetree
1018 : * @param rx_bufs Buffer array where data to be read will be written to.
1019 : *
1020 : * @return a value from spi_read().
1021 : */
1022 1 : static inline int spi_read_dt(const struct spi_dt_spec *spec,
1023 : const struct spi_buf_set *rx_bufs)
1024 : {
1025 : return spi_read(spec->bus, &spec->config, rx_bufs);
1026 : }
1027 :
1028 : /**
1029 : * @brief Write the specified amount of data from the SPI driver.
1030 : *
1031 : * @note This function is synchronous.
1032 : *
1033 : * @note This function is a helper function calling spi_transceive.
1034 : *
1035 : * @param dev Pointer to the device structure for the driver instance
1036 : * @param config Pointer to a valid spi_config structure instance.
1037 : * Pointer-comparison may be used to detect changes from
1038 : * previous operations.
1039 : * @param tx_bufs Buffer array where data to be sent originates from.
1040 : *
1041 : * @retval 0 If successful.
1042 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1043 : * device hardware or the driver software.
1044 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1045 : * @retval -errno Negative errno code on failure.
1046 : */
1047 1 : static inline int spi_write(const struct device *dev,
1048 : const struct spi_config *config,
1049 : const struct spi_buf_set *tx_bufs)
1050 : {
1051 : return spi_transceive(dev, config, tx_bufs, NULL);
1052 : }
1053 :
1054 : /**
1055 : * @brief Write data to a SPI bus specified in @p spi_dt_spec.
1056 : *
1057 : * This is equivalent to:
1058 : *
1059 : * spi_write(spec->bus, &spec->config, tx_bufs);
1060 : *
1061 : * @param spec SPI specification from devicetree
1062 : * @param tx_bufs Buffer array where data to be sent originates from.
1063 : *
1064 : * @return a value from spi_write().
1065 : */
1066 1 : static inline int spi_write_dt(const struct spi_dt_spec *spec,
1067 : const struct spi_buf_set *tx_bufs)
1068 : {
1069 : return spi_write(spec->bus, &spec->config, tx_bufs);
1070 : }
1071 : /** @} */
1072 :
1073 : #if defined(CONFIG_SPI_ASYNC) || defined(__DOXYGEN__)
1074 : /**
1075 : * @name SPI Asynchronous Transfer Functions
1076 : *
1077 : * With this API the transfer function will return after the transfer is started and
1078 : * report completion through a notification mechanism: callback or signal.
1079 : *
1080 : * @note Note that asynchronous API calls can still be blocking if the bus is already busy.
1081 : * The functions will block until the bus is available to start the requested transfer.
1082 : *
1083 : * @{
1084 : */
1085 :
1086 : /**
1087 : * @brief Read/write the specified amount of data from the SPI driver.
1088 : *
1089 : * @note This function is asynchronous.
1090 : *
1091 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1092 : * is selected.
1093 : *
1094 : * @note The chip select behavior as described by @ref spi_transceive and
1095 : * the function of controller/peripheral modes is the same.
1096 : *
1097 : * @param dev Pointer to the device structure for the driver instance
1098 : * @param config Pointer to a valid spi_config structure instance.
1099 : * Pointer-comparison may be used to detect changes from
1100 : * previous operations.
1101 : * @param tx_bufs Buffer array where data to be sent originates from,
1102 : * or NULL if none.
1103 : * @param rx_bufs Buffer array where data to be read will be written to,
1104 : * or NULL if none.
1105 : * @param callback Function pointer to completion callback.
1106 : * (Note: if NULL this function will not
1107 : * notify the end of the transaction, and whether it went
1108 : * successfully or not).
1109 : * @param userdata Userdata passed to callback
1110 : *
1111 : * @retval frames Positive number of frames received in slave mode.
1112 : * @retval 0 If successful in master mode.
1113 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1114 : * device hardware or the driver software.
1115 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1116 : * @retval -errno Negative errno code on failure.
1117 : */
1118 1 : static inline int spi_transceive_cb(const struct device *dev,
1119 : const struct spi_config *config,
1120 : const struct spi_buf_set *tx_bufs,
1121 : const struct spi_buf_set *rx_bufs,
1122 : spi_callback_t callback,
1123 : void *userdata)
1124 : {
1125 : const struct spi_driver_api *api =
1126 : (const struct spi_driver_api *)dev->api;
1127 :
1128 : return api->transceive_async(dev, config, tx_bufs, rx_bufs, callback, userdata);
1129 : }
1130 :
1131 : #if defined(CONFIG_POLL) || defined(__DOXYGEN__)
1132 :
1133 : /** @cond INTERNAL_HIDDEN */
1134 : void z_spi_transfer_signal_cb(const struct device *dev, int result, void *userdata);
1135 : /** @endcond */
1136 :
1137 : /**
1138 : * @brief Read/write the specified amount of data from the SPI driver.
1139 : *
1140 : * @note This function is asynchronous.
1141 : *
1142 : * @note The chip select behavior as described by @ref spi_transceive and
1143 : * the function of controller/peripheral modes is the same.
1144 : *
1145 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1146 : * and @kconfig{CONFIG_POLL} are selected.
1147 : *
1148 : * @param dev Pointer to the device structure for the driver instance
1149 : * @param config Pointer to a valid spi_config structure instance.
1150 : * Pointer-comparison may be used to detect changes from
1151 : * previous operations.
1152 : * @param tx_bufs Buffer array where data to be sent originates from,
1153 : * or NULL if none.
1154 : * @param rx_bufs Buffer array where data to be read will be written to,
1155 : * or NULL if none.
1156 : * @param sig A pointer to a valid and ready to be signaled
1157 : * struct k_poll_signal. (Note: if NULL this function will not
1158 : * notify the end of the transaction, and whether it went
1159 : * successfully or not).
1160 : *
1161 : * @retval frames Positive number of frames received in slave mode.
1162 : * @retval 0 If successful in master mode.
1163 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1164 : * device hardware or the driver software.
1165 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1166 : * @retval -errno Negative errno code on failure.
1167 : */
1168 1 : static inline int spi_transceive_signal(const struct device *dev,
1169 : const struct spi_config *config,
1170 : const struct spi_buf_set *tx_bufs,
1171 : const struct spi_buf_set *rx_bufs,
1172 : struct k_poll_signal *sig)
1173 : {
1174 : const struct spi_driver_api *api =
1175 : (const struct spi_driver_api *)dev->api;
1176 : spi_callback_t cb = (sig == NULL) ? NULL : z_spi_transfer_signal_cb;
1177 :
1178 : return api->transceive_async(dev, config, tx_bufs, rx_bufs, cb, sig);
1179 : }
1180 :
1181 : /**
1182 : * @brief Read the specified amount of data from the SPI driver.
1183 : *
1184 : * @note This function is asynchronous.
1185 : *
1186 : * @note This function is a helper function calling spi_transceive_signal.
1187 : *
1188 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1189 : * and @kconfig{CONFIG_POLL} are selected.
1190 : *
1191 : * @param dev Pointer to the device structure for the driver instance
1192 : * @param config Pointer to a valid spi_config structure instance.
1193 : * Pointer-comparison may be used to detect changes from
1194 : * previous operations.
1195 : * @param rx_bufs Buffer array where data to be read will be written to.
1196 : * @param sig A pointer to a valid and ready to be signaled
1197 : * struct k_poll_signal. (Note: if NULL this function will not
1198 : * notify the end of the transaction, and whether it went
1199 : * successfully or not).
1200 : *
1201 : * @retval frames Positive number of frames received in slave mode.
1202 : * @retval 0 If successful
1203 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1204 : * device hardware or the driver software.
1205 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1206 : * @retval -errno Negative errno code on failure.
1207 : */
1208 1 : static inline int spi_read_signal(const struct device *dev,
1209 : const struct spi_config *config,
1210 : const struct spi_buf_set *rx_bufs,
1211 : struct k_poll_signal *sig)
1212 : {
1213 : return spi_transceive_signal(dev, config, NULL, rx_bufs, sig);
1214 : }
1215 :
1216 : /**
1217 : * @brief Write the specified amount of data from the SPI driver.
1218 : *
1219 : * @note This function is asynchronous.
1220 : *
1221 : * @note This function is a helper function calling spi_transceive_signal.
1222 : *
1223 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1224 : * and @kconfig{CONFIG_POLL} are selected.
1225 : *
1226 : * @param dev Pointer to the device structure for the driver instance
1227 : * @param config Pointer to a valid spi_config structure instance.
1228 : * Pointer-comparison may be used to detect changes from
1229 : * previous operations.
1230 : * @param tx_bufs Buffer array where data to be sent originates from.
1231 : * @param sig A pointer to a valid and ready to be signaled
1232 : * struct k_poll_signal. (Note: if NULL this function will not
1233 : * notify the end of the transaction, and whether it went
1234 : * successfully or not).
1235 : *
1236 : * @retval 0 If successful.
1237 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1238 : * device hardware or the driver software.
1239 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1240 : * @retval -errno Negative errno code on failure.
1241 : */
1242 1 : static inline int spi_write_signal(const struct device *dev,
1243 : const struct spi_config *config,
1244 : const struct spi_buf_set *tx_bufs,
1245 : struct k_poll_signal *sig)
1246 : {
1247 : return spi_transceive_signal(dev, config, tx_bufs, NULL, sig);
1248 : }
1249 :
1250 : #endif /* CONFIG_POLL */
1251 :
1252 : /** @} */
1253 : #endif /* CONFIG_SPI_ASYNC */
1254 :
1255 :
1256 : #if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)
1257 :
1258 : /**
1259 : * @name SPI RTIO API
1260 : *
1261 : * Theses functions are for using the SPI driver class through an RTIO-based API
1262 : *
1263 : * @{
1264 : */
1265 : /**
1266 : * @brief Submit a SPI device with a request
1267 : *
1268 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1269 : * defined by SPI_IODEV_DEFINE.
1270 : * Must live as long as the request is in flight.
1271 : */
1272 1 : static inline void spi_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
1273 : {
1274 : const struct spi_dt_spec *dt_spec = (const struct spi_dt_spec *)iodev_sqe->sqe.iodev->data;
1275 : const struct device *dev = dt_spec->bus;
1276 : const struct spi_driver_api *api = (const struct spi_driver_api *)dev->api;
1277 :
1278 : api->iodev_submit(dt_spec->bus, iodev_sqe);
1279 : }
1280 :
1281 : /** @cond INTERNAL_HIDDEN */
1282 : extern const struct rtio_iodev_api spi_iodev_api;
1283 : /** @endcond */
1284 :
1285 : /**
1286 : * @brief Define an iodev for a given dt node on the bus
1287 : *
1288 : * These do not need to be shared globally but doing so
1289 : * will save a small amount of memory.
1290 : *
1291 : * @param name Symbolic name to use for defining the iodev
1292 : * @param node_id Devicetree node identifier
1293 : * @param operation_ SPI operational mode
1294 : * @param delay_ Chip select delay in microseconds
1295 : */
1296 1 : #define SPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_) \
1297 : const struct spi_dt_spec _spi_dt_spec_##name = \
1298 : SPI_DT_SPEC_GET(node_id, operation_, delay_); \
1299 : RTIO_IODEV_DEFINE(name, &spi_iodev_api, (void *)&_spi_dt_spec_##name)
1300 :
1301 : /**
1302 : * @brief Validate that SPI bus (and CS gpio if defined) is ready.
1303 : *
1304 : * @param spi_iodev SPI iodev defined with SPI_DT_IODEV_DEFINE
1305 : *
1306 : * @retval true if the SPI bus is ready for use.
1307 : * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
1308 : */
1309 1 : static inline bool spi_is_ready_iodev(const struct rtio_iodev *spi_iodev)
1310 : {
1311 : struct spi_dt_spec *spec = (struct spi_dt_spec *)spi_iodev->data;
1312 :
1313 : return spi_is_ready_dt(spec);
1314 : }
1315 : /** @} */
1316 :
1317 : #endif /* CONFIG_SPI_RTIO */
1318 :
1319 : /**
1320 : * @brief Release the SPI device locked on and/or the CS by the current config
1321 : *
1322 : * Note: This synchronous function is used to release either the lock on the
1323 : * SPI device and/or the CS line that was kept if, and if only,
1324 : * given config parameter was the last one to be used (in any of the
1325 : * above functions) and if it has the SPI_LOCK_ON bit set and/or the
1326 : * SPI_HOLD_ON_CS bit set into its operation bits field.
1327 : * This can be used if the caller needs to keep its hand on the SPI
1328 : * device for consecutive transactions and/or if it needs the device to
1329 : * stay selected. Usually both bits will be used along each other, so the
1330 : * the device is locked and stays on until another operation is necessary
1331 : * or until it gets released with the present function.
1332 : *
1333 : * @param dev Pointer to the device structure for the driver instance
1334 : * @param config Pointer to a valid spi_config structure instance.
1335 : *
1336 : * @retval 0 If successful.
1337 : * @retval -errno Negative errno code on failure.
1338 : */
1339 1 : __syscall int spi_release(const struct device *dev,
1340 : const struct spi_config *config);
1341 :
1342 : static inline int z_impl_spi_release(const struct device *dev,
1343 : const struct spi_config *config)
1344 : {
1345 : const struct spi_driver_api *api =
1346 : (const struct spi_driver_api *)dev->api;
1347 :
1348 : return api->release(dev, config);
1349 : }
1350 :
1351 : /**
1352 : * @brief Release the SPI device specified in @p spi_dt_spec.
1353 : *
1354 : * This is equivalent to:
1355 : *
1356 : * spi_release(spec->bus, &spec->config);
1357 : *
1358 : * @param spec SPI specification from devicetree
1359 : *
1360 : * @return a value from spi_release().
1361 : */
1362 1 : static inline int spi_release_dt(const struct spi_dt_spec *spec)
1363 : {
1364 : return spi_release(spec->bus, &spec->config);
1365 : }
1366 :
1367 : #ifdef __cplusplus
1368 : }
1369 : #endif
1370 :
1371 : /**
1372 : * @}
1373 : */
1374 :
1375 : #include <zephyr/syscalls/spi.h>
1376 :
1377 : /**
1378 : * @}
1379 : */
1380 : #endif /* ZEPHYR_INCLUDE_DRIVERS_SPI_H_ */
|
