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.1.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 : union {
246 : struct {
247 : /**
248 : * GPIO devicetree specification of CS GPIO.
249 : * The device pointer can be set to NULL to fully inhibit CS control if
250 : * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
251 : * equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct
252 : * spi_config.
253 : */
254 1 : struct gpio_dt_spec gpio;
255 : /**
256 : * Delay in microseconds to wait before starting the
257 : * transmission and before releasing the CS line.
258 : */
259 1 : uint32_t delay;
260 : };
261 : struct {
262 : /**
263 : * CS enable lead time, i.e. how long should the CS be asserted
264 : * before the first clock. Specified in nanoseconds.
265 : */
266 1 : uint32_t setup_ns;
267 : /**
268 : * CS enable lag time, i.e. how long should the CS be asserted
269 : * after the last clock, before the CS de-asserts.
270 : * Specified in nanoseconds.
271 : */
272 1 : uint32_t hold_ns;
273 : };
274 0 : };
275 : /* To keep track of which form of this struct is valid */
276 0 : bool cs_is_gpio;
277 : };
278 :
279 : /**
280 : * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
281 : *
282 : * Example devicetree fragment:
283 : *
284 : * @code{.devicetree}
285 : * gpio1: gpio@abcd0001 { ... };
286 : *
287 : * gpio2: gpio@abcd0002 { ... };
288 : *
289 : * spi@abcd0003 {
290 : * compatible = "vnd,spi";
291 : * cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
292 : * <&gpio2 20 GPIO_ACTIVE_LOW>;
293 : *
294 : * a: spi-dev-a@0 {
295 : * reg = <0>;
296 : * };
297 : *
298 : * b: spi-dev-b@1 {
299 : * reg = <1>;
300 : * };
301 : * };
302 : * @endcode
303 : *
304 : * Example usage:
305 : *
306 : * @code{.c}
307 : * SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(a)) \
308 : * // { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
309 : * SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(b)) \
310 : * // { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }
311 : * @endcode
312 : *
313 : * @param spi_dev a SPI device node identifier
314 : * @return #gpio_dt_spec struct corresponding with spi_dev's chip select
315 : */
316 1 : #define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev) \
317 : GPIO_DT_SPEC_GET_BY_IDX_OR(DT_BUS(spi_dev), cs_gpios, \
318 : DT_REG_ADDR_RAW(spi_dev), {})
319 :
320 : /**
321 : * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
322 : *
323 : * This is equivalent to
324 : * <tt>SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))</tt>.
325 : *
326 : * @param inst Devicetree instance number
327 : * @return #gpio_dt_spec struct corresponding with spi_dev's chip select
328 : */
329 1 : #define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
330 : SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))
331 :
332 : /** @cond INTERNAL_HIDDEN */
333 : #define SPI_CS_CONTROL_MAX_DELAY(node_id) \
334 : MAX(DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0), \
335 : DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0))
336 :
337 :
338 : #define SPI_CS_CONTROL_INIT_GPIO(node_id, ...) \
339 : .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id), \
340 : .delay = COND_CODE_1(IS_EMPTY(__VA_ARGS__), \
341 : (DIV_ROUND_UP(SPI_CS_CONTROL_MAX_DELAY(node_id), 1000)), \
342 : (__VA_ARGS__))
343 :
344 : #define SPI_CS_CONTROL_INIT_NATIVE(node_id) \
345 : .setup_ns = DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0), \
346 : .hold_ns = DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0),
347 :
348 : #define SPI_DEPRECATE_DELAY_WARN \
349 : __WARN("Delay parameter in SPI DT macros is deprecated, use DT prop instead")
350 : /** @endcond */
351 :
352 : /**
353 : * @brief Initialize and get a pointer to a @p spi_cs_control from a
354 : * devicetree node identifier
355 : *
356 : * This helper is useful for initializing a device on a SPI bus. It
357 : * initializes a struct spi_cs_control and returns a pointer to it.
358 : * Here, @p node_id is a node identifier for a SPI device, not a SPI
359 : * controller.
360 : *
361 : * Example devicetree fragment:
362 : *
363 : * @code{.devicetree}
364 : * spi@abcd0001 {
365 : * cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
366 : * spidev: spi-device@0 { ... };
367 : * };
368 : * @endcode
369 : *
370 : * Example usage:
371 : *
372 : * @code{.c}
373 : * struct spi_cs_control ctrl =
374 : * SPI_CS_CONTROL_INIT(DT_NODELABEL(spidev));
375 : * @endcode
376 : *
377 : * This example is roughly equivalent to:
378 : *
379 : * @code{.c}
380 : * struct spi_cs_control ctrl = {
381 : * .gpio = SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(spidev)),
382 : * .delay = DT_PROP(node_id, cs_delay_ns) / 1000,
383 : * .cs_is_gpio = true,
384 : * };
385 : * @endcode
386 : *
387 : * For non-gpio CS, the idea is similar but the lead and lag fields of the cs struct
388 : * will be populated instead.
389 : *
390 : * @param node_id Devicetree node identifier for a device on a SPI bus
391 : *
392 : * @return a pointer to the @p spi_cs_control structure
393 : */
394 1 : #define SPI_CS_CONTROL_INIT(node_id, ...) \
395 : { \
396 : COND_CODE_0(IS_EMPTY(__VA_ARGS__), (SPI_DEPRECATE_DELAY_WARN), ()) \
397 : .cs_is_gpio = DT_SPI_DEV_HAS_CS_GPIOS(node_id), \
398 : COND_CODE_1(DT_SPI_DEV_HAS_CS_GPIOS(node_id), \
399 : (SPI_CS_CONTROL_INIT_GPIO(node_id, __VA_ARGS__)), \
400 : (SPI_CS_CONTROL_INIT_NATIVE(node_id))) \
401 : }
402 :
403 : /**
404 : * @brief Get a pointer to a @p spi_cs_control from a devicetree node
405 : *
406 : * This is equivalent to
407 : * <tt>SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay)</tt>.
408 : *
409 : * Therefore, @p DT_DRV_COMPAT must already be defined before using
410 : * this macro.
411 : *
412 : * @param inst Devicetree node instance number
413 : *
414 : * @return a pointer to the @p spi_cs_control structure
415 : */
416 1 : #define SPI_CS_CONTROL_INIT_INST(inst) \
417 : SPI_CS_CONTROL_INIT(DT_DRV_INST(inst))
418 :
419 : /** @} */
420 :
421 : /**
422 : * @typedef spi_operation_t
423 : * Opaque type to hold the SPI operation flags.
424 : */
425 : #if defined(CONFIG_SPI_EXTENDED_MODES)
426 : typedef uint32_t spi_operation_t;
427 : #else
428 1 : typedef uint16_t spi_operation_t;
429 : #endif
430 :
431 : /**
432 : * @brief SPI controller configuration structure
433 : *
434 : * @warning Most drivers use pointer comparison to determine whether a passed
435 : * configuration is different from one used in a previous transaction.
436 : * Changes to fields in the structure may not be detected.
437 : */
438 1 : struct spi_config {
439 : /** @brief Bus frequency in Hertz. */
440 1 : uint32_t frequency;
441 : /**
442 : * @brief Operation flags.
443 : *
444 : * It is a bit field with the following parts:
445 : *
446 : * - 0: Master or slave.
447 : * - 1..3: Clock polarity, phase and loop mode.
448 : * - 4: LSB or MSB first.
449 : * - 5..10: Size of a data frame (word) in bits.
450 : * - 11: Full/half duplex.
451 : * - 12: Hold on the CS line if possible.
452 : * - 13: Keep resource locked for the caller.
453 : * - 14: Active high CS logic.
454 : * - 15: Motorola or TI frame format (optional).
455 : *
456 : * If @kconfig{CONFIG_SPI_EXTENDED_MODES} is enabled:
457 : *
458 : * - 16..17: MISO lines (Single/Dual/Quad/Octal).
459 : * - 18..31: Reserved for future use.
460 : */
461 1 : spi_operation_t operation;
462 : /** @brief Slave number from 0 to host controller slave limit. */
463 1 : uint16_t slave;
464 : /**
465 : * @brief GPIO chip-select line (optional, must be initialized to zero
466 : * if not used).
467 : */
468 1 : struct spi_cs_control cs;
469 : /**
470 : * @brief Delay between SPI words on SCK line in nanoseconds, if supported.
471 : * Value of zero will attempt to use half of the SCK period.
472 : */
473 1 : uint16_t word_delay;
474 : };
475 :
476 : /** @cond INTERNAL_HIDDEN */
477 : /* converts from the special DT zero value to half of the frequency, for drivers usage mostly */
478 : static inline uint16_t spi_get_word_delay(const struct spi_config *cfg)
479 : {
480 : uint32_t freq = cfg->frequency;
481 :
482 : if (cfg->word_delay != 0) {
483 : return cfg->word_delay;
484 : }
485 :
486 : if (freq == 0) {
487 : return 0;
488 : }
489 :
490 : uint64_t period_ns = NSEC_PER_SEC / freq;
491 :
492 : period_ns = MIN(period_ns, UINT16_MAX);
493 : period_ns /= 2;
494 :
495 : return (uint16_t)period_ns;
496 : }
497 : /** @endcond */
498 :
499 : /**
500 : * @brief Structure initializer for spi_config from devicetree
501 : *
502 : * This helper macro expands to a static initializer for a <tt>struct
503 : * spi_config</tt> by reading the relevant @p frequency, @p slave, and
504 : * @p cs data from the devicetree.
505 : *
506 : * @param node_id Devicetree node identifier for the SPI device whose
507 : * struct spi_config to create an initializer for
508 : * @param operation_ the desired @p operation field in the struct spi_config
509 : */
510 1 : #define SPI_CONFIG_DT(node_id, operation_, ...) \
511 : { \
512 : .frequency = DT_PROP(node_id, spi_max_frequency), \
513 : .operation = (operation_) | \
514 : DT_PROP(node_id, duplex) | \
515 : DT_PROP(node_id, frame_format) | \
516 : COND_CODE_1(DT_PROP(node_id, spi_cpol), SPI_MODE_CPOL, (0)) | \
517 : COND_CODE_1(DT_PROP(node_id, spi_cpha), SPI_MODE_CPHA, (0)) | \
518 : COND_CODE_1(DT_PROP(node_id, spi_hold_cs), SPI_HOLD_ON_CS, (0)) | \
519 : COND_CODE_1(DT_PROP(node_id, spi_lsb_first), SPI_TRANSFER_LSB, (0)) | \
520 : COND_CODE_1(DT_PROP(node_id, spi_cs_high), SPI_CS_ACTIVE_HIGH, (0)), \
521 : .slave = DT_REG_ADDR(node_id), \
522 : .cs = SPI_CS_CONTROL_INIT(node_id, __VA_ARGS__), \
523 : .word_delay = DT_PROP(node_id, spi_interframe_delay_ns),\
524 : }
525 :
526 : /**
527 : * @brief Structure initializer for spi_config from devicetree instance
528 : *
529 : * This is equivalent to
530 : * <tt>SPI_CONFIG_DT(DT_DRV_INST(inst), operation_)</tt>.
531 : *
532 : * @param inst Devicetree instance number
533 : * @param operation_ the desired @p operation field in the struct spi_config
534 : */
535 1 : #define SPI_CONFIG_DT_INST(inst, operation_, ...) \
536 : SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, __VA_ARGS__)
537 :
538 : /**
539 : * @brief Complete SPI DT information
540 : */
541 1 : struct spi_dt_spec {
542 : /** SPI bus */
543 1 : const struct device *bus;
544 : /** Slave specific configuration */
545 1 : struct spi_config config;
546 : };
547 :
548 : /**
549 : * @brief Structure initializer for spi_dt_spec from devicetree
550 : *
551 : * This helper macro expands to a static initializer for a <tt>struct
552 : * spi_dt_spec</tt> by reading the relevant bus, frequency, slave, and cs
553 : * data from the devicetree.
554 : *
555 : * Important: multiple fields are automatically constructed by this macro
556 : * which must be checked before use. @ref spi_is_ready_dt performs the required
557 : * @ref device_is_ready checks.
558 : *
559 : * @param node_id Devicetree node identifier for the SPI device whose
560 : * struct spi_dt_spec to create an initializer for
561 : * @param operation_ the desired @p operation field in the struct spi_config
562 : */
563 1 : #define SPI_DT_SPEC_GET(node_id, operation_, ...) \
564 : { \
565 : .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
566 : .config = SPI_CONFIG_DT(node_id, operation_, __VA_ARGS__), \
567 : }
568 :
569 : /**
570 : * @brief Structure initializer for spi_dt_spec from devicetree instance
571 : *
572 : * This is equivalent to
573 : * <tt>SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_)</tt>.
574 : *
575 : * @param inst Devicetree instance number
576 : * @param operation_ the desired @p operation field in the struct spi_config
577 : */
578 1 : #define SPI_DT_SPEC_INST_GET(inst, operation_, ...) \
579 : SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, __VA_ARGS__)
580 :
581 : /**
582 : * @brief Value that will never compare true with any valid overrun character
583 : */
584 1 : #define SPI_MOSI_OVERRUN_UNKNOWN 0x100
585 :
586 : /**
587 : * @brief The value sent on MOSI when all TX bytes are sent, but RX continues
588 : *
589 : * For drivers where the MOSI line state when receiving is important, this value
590 : * can be queried at compile-time to determine whether allocating a constant
591 : * array is necessary.
592 : *
593 : * @param node_id Devicetree node identifier for the SPI device to query
594 : *
595 : * @retval SPI_MOSI_OVERRUN_UNKNOWN if controller does not export the value
596 : * @retval byte default MOSI value otherwise
597 : */
598 1 : #define SPI_MOSI_OVERRUN_DT(node_id) \
599 : DT_PROP_OR(node_id, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
600 :
601 : /**
602 : * @brief The value sent on MOSI when all TX bytes are sent, but RX continues
603 : *
604 : * This is equivalent to
605 : * <tt>SPI_MOSI_OVERRUN_DT(DT_DRV_INST(inst))</tt>.
606 : *
607 : * @param inst Devicetree instance number
608 : *
609 : * @retval SPI_MOSI_OVERRUN_UNKNOWN if controller does not export the value
610 : * @retval byte default MOSI value otherwise
611 : */
612 1 : #define SPI_MOSI_OVERRUN_DT_INST(inst) \
613 : DT_INST_PROP_OR(inst, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
614 :
615 : /**
616 : * @brief SPI buffer structure
617 : *
618 : * A SPI buffer describes either a real data buffer or an indication of NOP
619 : * For a NOP indicator:
620 : * If buffer is used for TX, only 0's will be sent for the length on the bus
621 : * If buffer is used for RX, that length of data received by bus will be ignored/skipped
622 : */
623 1 : struct spi_buf {
624 : /** Valid pointer to a data buffer, or NULL for NOP indication */
625 1 : void *buf;
626 : /** Length of the buffer @a buf in bytes, or length of NOP */
627 1 : size_t len;
628 : };
629 :
630 : /**
631 : * @brief SPI scatter-gather buffer array structure
632 : *
633 : * A spi_buf_set is a flexible description of a whole single SPI bus transfer.
634 : *
635 : * Since the set is an array of pointers to buffers, it means that pieces of a spi transfer
636 : * definition can be re-used across different transfers, without having to redefine or allocate
637 : * new memory for them each time.
638 : * This accomplishes what is called "scatter-gather" buffer management at the driver level with
639 : * user-provided buffers.
640 : */
641 1 : struct spi_buf_set {
642 : /** Pointer to an array of spi_buf, or NULL */
643 1 : const struct spi_buf *buffers;
644 : /** Number of buffers in the array pointed to: by @a buffers */
645 1 : size_t count;
646 : };
647 :
648 : /**
649 : * @name SPI Stats
650 : * @{
651 : */
652 : #if defined(CONFIG_SPI_STATS)
653 : STATS_SECT_START(spi)
654 : STATS_SECT_ENTRY32(rx_bytes)
655 : STATS_SECT_ENTRY32(tx_bytes)
656 : STATS_SECT_ENTRY32(transfer_error)
657 : STATS_SECT_END;
658 :
659 : STATS_NAME_START(spi)
660 : STATS_NAME(spi, rx_bytes)
661 : STATS_NAME(spi, tx_bytes)
662 : STATS_NAME(spi, transfer_error)
663 : STATS_NAME_END(spi);
664 :
665 : /**
666 : * @brief SPI specific device state which allows for SPI device class specific additions
667 : */
668 : struct spi_device_state {
669 : struct device_state devstate;
670 : struct stats_spi stats;
671 : };
672 :
673 : /**
674 : * @brief Get pointer to SPI statistics structure
675 : */
676 : #define Z_SPI_GET_STATS(dev_) \
677 : CONTAINER_OF(dev_->state, struct spi_device_state, devstate)->stats
678 :
679 : /**
680 : * @brief Increment the rx bytes for a SPI device
681 : *
682 : * @param dev_ Pointer to the device structure for the driver instance.
683 : */
684 : #define SPI_STATS_RX_BYTES_INCN(dev_, n) \
685 : STATS_INCN(Z_SPI_GET_STATS(dev_), rx_bytes, n)
686 :
687 : /**
688 : * @brief Increment the tx bytes for a SPI device
689 : *
690 : * @param dev_ Pointer to the device structure for the driver instance.
691 : */
692 : #define SPI_STATS_TX_BYTES_INCN(dev_, n) \
693 : STATS_INCN(Z_SPI_GET_STATS(dev_), tx_bytes, n)
694 :
695 : /**
696 : * @brief Increment the transfer error counter for a SPI device
697 : *
698 : * The transfer error count is incremented when there occurred a transfer error
699 : *
700 : * @param dev_ Pointer to the device structure for the driver instance.
701 : */
702 : #define SPI_STATS_TRANSFER_ERROR_INC(dev_) \
703 : STATS_INC(Z_SPI_GET_STATS(dev_), transfer_error)
704 :
705 : /** @cond INTERNAL_HIDDEN */
706 : /**
707 : * @brief Define a statically allocated and section assigned SPI device state
708 : */
709 : #define Z_SPI_DEVICE_STATE_DEFINE(dev_id) \
710 : static struct spi_device_state Z_DEVICE_STATE_NAME(dev_id) \
711 : __attribute__((__section__(".z_devstate")));
712 :
713 : /**
714 : * @brief Define an SPI device init wrapper function
715 : *
716 : * This does device instance specific initialization of common data (such as stats)
717 : * and calls the given init_fn
718 : */
719 : #define Z_SPI_INIT_FN(dev_id, init_fn) \
720 : static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
721 : { \
722 : struct spi_device_state *state = \
723 : CONTAINER_OF(dev->state, struct spi_device_state, devstate); \
724 : stats_init(&state->stats.s_hdr, STATS_SIZE_32, 3, \
725 : STATS_NAME_INIT_PARMS(spi)); \
726 : stats_register(dev->name, &(state->stats.s_hdr)); \
727 : return init_fn(dev); \
728 : }
729 : /** @endcond */
730 :
731 : #define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, \
732 : pm_device, data_ptr, cfg_ptr, \
733 : level, prio, api_ptr, ...) \
734 : Z_SPI_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
735 : Z_SPI_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
736 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
737 : DEVICE_DT_NAME(node_id), \
738 : &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
739 : deinit_fn, Z_DEVICE_DT_FLAGS(node_id), \
740 : pm_device, data_ptr, cfg_ptr, level, prio, \
741 : api_ptr, \
742 : &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
743 : __VA_ARGS__)
744 :
745 : static inline void spi_transceive_stats(const struct device *dev, int error,
746 : const struct spi_buf_set *tx_bufs,
747 : const struct spi_buf_set *rx_bufs)
748 : {
749 : uint32_t tx_bytes;
750 : uint32_t rx_bytes;
751 :
752 : if (error) {
753 : SPI_STATS_TRANSFER_ERROR_INC(dev);
754 : }
755 :
756 : if (tx_bufs) {
757 : tx_bytes = tx_bufs->count ? tx_bufs->buffers->len : 0;
758 : SPI_STATS_TX_BYTES_INCN(dev, tx_bytes);
759 : }
760 :
761 : if (rx_bufs) {
762 : rx_bytes = rx_bufs->count ? rx_bufs->buffers->len : 0;
763 : SPI_STATS_RX_BYTES_INCN(dev, rx_bytes);
764 : }
765 : }
766 : /** @} */
767 :
768 : #else /*CONFIG_SPI_STATS*/
769 :
770 : /**
771 : * @name SPI DT Device Macros
772 : * @{
773 : */
774 :
775 : /**
776 : * @brief Like DEVICE_DT_DEINIT_DEFINE() with SPI specifics.
777 : *
778 : * @details Defines a device which implements the SPI API. May
779 : * generate a custom device_state container struct and init_fn
780 : * wrapper when needed depending on SPI @kconfig{CONFIG_SPI_STATS}.
781 : *
782 : * @param node_id The devicetree node identifier.
783 : * @param init_fn Name of the init function of the driver.
784 : * @param deinit_fn Name of the deinit function of the driver.
785 : * @param pm PM device resources reference (NULL if device does not use PM).
786 : * @param data Pointer to the device's private data.
787 : * @param config The address to the structure containing the configuration
788 : * information for this instance of the driver.
789 : * @param level The initialization level. See SYS_INIT() for details.
790 : * @param prio Priority within the selected initialization level. See SYS_INIT()
791 : * for details.
792 : * @param api Provides an initial pointer to the API function struct used by
793 : * the driver. Can be NULL.
794 : */
795 : #define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, data, \
796 1 : config, level, prio, api, ...) \
797 : Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
798 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
799 : DEVICE_DT_NAME(node_id), init_fn, deinit_fn, \
800 : Z_DEVICE_DT_FLAGS(node_id), pm, data, config, \
801 : level, prio, api, \
802 : &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)), \
803 : __VA_ARGS__)
804 :
805 : /** @} */
806 :
807 0 : #define SPI_STATS_RX_BYTES_INC(dev_)
808 0 : #define SPI_STATS_TX_BYTES_INC(dev_)
809 0 : #define SPI_STATS_TRANSFER_ERROR_INC(dev_)
810 :
811 0 : #define spi_transceive_stats(dev, error, tx_bufs, rx_bufs)
812 :
813 : #endif /*CONFIG_SPI_STATS*/
814 :
815 : /**
816 : * @brief Like DEVICE_DT_DEINIT_DEFINE() without deinit function.
817 : *
818 : * @details Defines a device which implements the SPI API. May
819 : * generate a custom device_state container struct and init_fn
820 : * wrapper when needed depending on SPI @kconfig{CONFIG_SPI_STATS}.
821 : *
822 : * @param node_id The devicetree node identifier.
823 : * @param init_fn Name of the init function of the driver.
824 : * @param pm PM device resources reference (NULL if device does not use PM).
825 : * @param data Pointer to the device's private data.
826 : * @param config The address to the structure containing the configuration
827 : * information for this instance of the driver.
828 : * @param level The initialization level. See SYS_INIT() for details.
829 : * @param prio Priority within the selected initialization level. See SYS_INIT()
830 : * for details.
831 : * @param api Provides an initial pointer to the API function struct used by
832 : * the driver. Can be NULL.
833 : */
834 : #define SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, \
835 1 : api, ...) \
836 : SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, NULL, pm, data, config, \
837 : level, prio, api, __VA_ARGS__)
838 :
839 : /**
840 : * @brief Like SPI_DEVICE_DT_DEINIT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT`
841 : * compatible instead of a node identifier.
842 : *
843 : * @param inst Instance number. The `node_id` argument to SPI_DEVICE_DT_DEINIT_DEFINE() is
844 : * set to `DT_DRV_INST(inst)`.
845 : * @param ... Other parameters as expected by SPI_DEVICE_DT_DEFINE().
846 : */
847 1 : #define SPI_DEVICE_DT_INST_DEINIT_DEFINE(inst, ...) \
848 : SPI_DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
849 :
850 : /**
851 : * @brief Like SPI_DEVICE_DT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT`
852 : * compatible instead of a node identifier.
853 : *
854 : * @param inst Instance number. The `node_id` argument to SPI_DEVICE_DT_DEFINE() is
855 : * set to `DT_DRV_INST(inst)`.
856 : * @param ... Other parameters as expected by SPI_DEVICE_DT_DEFINE().
857 : */
858 1 : #define SPI_DEVICE_DT_INST_DEFINE(inst, ...) \
859 : SPI_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
860 :
861 : /**
862 : * @typedef spi_api_io
863 : * @brief Callback API for I/O
864 : * See spi_transceive() for argument descriptions
865 : */
866 1 : typedef int (*spi_api_io)(const struct device *dev,
867 : const struct spi_config *config,
868 : const struct spi_buf_set *tx_bufs,
869 : const struct spi_buf_set *rx_bufs);
870 :
871 : /**
872 : * @brief SPI callback for asynchronous transfer requests
873 : *
874 : * @param dev SPI device which is notifying of transfer completion or error
875 : * @param result Result code of the transfer request. 0 is success, -errno for failure.
876 : * @param data Transfer requester supplied data which is passed along to the callback.
877 : */
878 1 : typedef void (*spi_callback_t)(const struct device *dev, int result, void *data);
879 :
880 : /**
881 : * @typedef spi_api_io
882 : * @brief Callback API for asynchronous I/O
883 : * See spi_transceive_signal() for argument descriptions
884 : */
885 0 : typedef int (*spi_api_io_async)(const struct device *dev,
886 : const struct spi_config *config,
887 : const struct spi_buf_set *tx_bufs,
888 : const struct spi_buf_set *rx_bufs,
889 : spi_callback_t cb,
890 : void *userdata);
891 :
892 : #if defined(CONFIG_SPI_RTIO) || defined(DOXYGEN)
893 :
894 : /**
895 : * @typedef spi_api_iodev_submit
896 : * @brief Callback API for submitting work to a SPI device with RTIO
897 : */
898 : typedef void (*spi_api_iodev_submit)(const struct device *dev,
899 : struct rtio_iodev_sqe *iodev_sqe);
900 : #endif /* CONFIG_SPI_RTIO */
901 :
902 : /**
903 : * @typedef spi_api_release
904 : * @brief Callback API for unlocking SPI device.
905 : * See spi_release() for argument descriptions
906 : */
907 1 : typedef int (*spi_api_release)(const struct device *dev,
908 : const struct spi_config *config);
909 :
910 :
911 : /**
912 : * @brief SPI driver API
913 : * This is the mandatory API any SPI driver needs to expose.
914 : */
915 1 : __subsystem struct spi_driver_api {
916 0 : spi_api_io transceive;
917 : #ifdef CONFIG_SPI_ASYNC
918 : spi_api_io_async transceive_async;
919 : #endif /* CONFIG_SPI_ASYNC */
920 : #ifdef CONFIG_SPI_RTIO
921 : spi_api_iodev_submit iodev_submit;
922 : #endif /* CONFIG_SPI_RTIO */
923 0 : spi_api_release release;
924 : };
925 :
926 : /**
927 : * @brief Check if SPI CS is controlled using a GPIO.
928 : *
929 : * @param config SPI configuration.
930 : * @return true If CS is controlled using a GPIO.
931 : * @return false If CS is controlled by hardware or any other means.
932 : */
933 1 : static inline bool spi_cs_is_gpio(const struct spi_config *config)
934 : {
935 : return config->cs.cs_is_gpio;
936 : }
937 :
938 : /**
939 : * @brief Check if SPI CS in @ref spi_dt_spec is controlled using a GPIO.
940 : *
941 : * @param spec SPI specification from devicetree.
942 : * @return true If CS is controlled using a GPIO.
943 : * @return false If CS is controlled by hardware or any other means.
944 : */
945 1 : static inline bool spi_cs_is_gpio_dt(const struct spi_dt_spec *spec)
946 : {
947 : return spi_cs_is_gpio(&spec->config);
948 : }
949 :
950 : /**
951 : * @brief Validate that SPI bus (and CS gpio if defined) is ready.
952 : *
953 : * @param spec SPI specification from devicetree
954 : *
955 : * @retval true if the SPI bus is ready for use.
956 : * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
957 : */
958 1 : static inline bool spi_is_ready_dt(const struct spi_dt_spec *spec)
959 : {
960 : /* Validate bus is ready */
961 : if (!device_is_ready(spec->bus)) {
962 : return false;
963 : }
964 : /* Validate CS gpio port is ready, if it is used */
965 : if (spi_cs_is_gpio_dt(spec) &&
966 : !gpio_is_ready_dt(&spec->config.cs.gpio)) {
967 : return false;
968 : }
969 : return true;
970 : }
971 :
972 : /**
973 : * @name SPI Synchronous Transfer Functions
974 : *
975 : * These functions will not return until transfer is complete
976 : *
977 : * @{
978 : */
979 :
980 : /**
981 : * @brief Read/write the specified amount of data from the SPI driver.
982 : *
983 : * @note This function is synchronous.
984 : *
985 : * @note In master mode, the chip select line will remain asserted (active) for
986 : * the entire duration of the transfer of all buffers in the provided buf sets.
987 : * Only after all buffers have been transferred will CS be deasserted.
988 : *
989 : * @note In peripheral mode, data transfer happens when the master asserts CS and
990 : * provides the clock. The function will wait for the master to complete
991 : * the transfer before returning. The CS is controlled by master
992 : * and therefore may not be continuously asserted for the whole transfer.
993 : *
994 : * @param dev Pointer to the device structure for the driver instance
995 : * @param config Pointer to a valid spi_config structure instance.
996 : * Pointer-comparison may be used to detect changes from
997 : * previous operations.
998 : * @param tx_bufs Buffer array where data to be sent originates from,
999 : * or NULL if none.
1000 : * @param rx_bufs Buffer array where data to be read will be written to,
1001 : * or NULL if none.
1002 : *
1003 : * @retval frames Positive number of frames received in slave mode.
1004 : * @retval 0 If successful in master mode.
1005 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1006 : * device hardware or the driver software.
1007 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1008 : * @retval -errno Negative errno code on failure.
1009 : */
1010 1 : __syscall int spi_transceive(const struct device *dev,
1011 : const struct spi_config *config,
1012 : const struct spi_buf_set *tx_bufs,
1013 : const struct spi_buf_set *rx_bufs);
1014 :
1015 : static inline int z_impl_spi_transceive(const struct device *dev,
1016 : const struct spi_config *config,
1017 : const struct spi_buf_set *tx_bufs,
1018 : const struct spi_buf_set *rx_bufs)
1019 : {
1020 : const struct spi_driver_api *api =
1021 : (const struct spi_driver_api *)dev->api;
1022 : int ret;
1023 :
1024 : ret = api->transceive(dev, config, tx_bufs, rx_bufs);
1025 : spi_transceive_stats(dev, ret, tx_bufs, rx_bufs);
1026 :
1027 : return ret;
1028 : }
1029 :
1030 : /**
1031 : * @brief Read/write data from an SPI bus specified in @p spi_dt_spec.
1032 : *
1033 : * This is equivalent to:
1034 : *
1035 : * spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
1036 : *
1037 : * @param spec SPI specification from devicetree
1038 : * @param tx_bufs Buffer array where data to be sent originates from,
1039 : * or NULL if none.
1040 : * @param rx_bufs Buffer array where data to be read will be written to,
1041 : * or NULL if none.
1042 : *
1043 : * @return a value from spi_transceive().
1044 : */
1045 1 : static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
1046 : const struct spi_buf_set *tx_bufs,
1047 : const struct spi_buf_set *rx_bufs)
1048 : {
1049 : return spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
1050 : }
1051 :
1052 : /**
1053 : * @brief Read the specified amount of data from the SPI driver.
1054 : *
1055 : * @note This function is synchronous.
1056 : *
1057 : * @note This function is a helper function calling spi_transceive.
1058 : *
1059 : * @param dev Pointer to the device structure for the driver instance
1060 : * @param config Pointer to a valid spi_config structure instance.
1061 : * Pointer-comparison may be used to detect changes from
1062 : * previous operations.
1063 : * @param rx_bufs Buffer array where data to be read will be written to.
1064 : *
1065 : * @retval frames Positive number of frames received in slave mode.
1066 : * @retval 0 If successful.
1067 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1068 : * device hardware or the driver software.
1069 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1070 : * @retval -errno Negative errno code on failure.
1071 : */
1072 1 : static inline int spi_read(const struct device *dev,
1073 : const struct spi_config *config,
1074 : const struct spi_buf_set *rx_bufs)
1075 : {
1076 : return spi_transceive(dev, config, NULL, rx_bufs);
1077 : }
1078 :
1079 : /**
1080 : * @brief Read data from a SPI bus specified in @p spi_dt_spec.
1081 : *
1082 : * This is equivalent to:
1083 : *
1084 : * spi_read(spec->bus, &spec->config, rx_bufs);
1085 : *
1086 : * @param spec SPI specification from devicetree
1087 : * @param rx_bufs Buffer array where data to be read will be written to.
1088 : *
1089 : * @return a value from spi_read().
1090 : */
1091 1 : static inline int spi_read_dt(const struct spi_dt_spec *spec,
1092 : const struct spi_buf_set *rx_bufs)
1093 : {
1094 : return spi_read(spec->bus, &spec->config, rx_bufs);
1095 : }
1096 :
1097 : /**
1098 : * @brief Write the specified amount of data from the SPI driver.
1099 : *
1100 : * @note This function is synchronous.
1101 : *
1102 : * @note This function is a helper function calling spi_transceive.
1103 : *
1104 : * @param dev Pointer to the device structure for the driver instance
1105 : * @param config Pointer to a valid spi_config structure instance.
1106 : * Pointer-comparison may be used to detect changes from
1107 : * previous operations.
1108 : * @param tx_bufs Buffer array where data to be sent originates from.
1109 : *
1110 : * @retval 0 If successful.
1111 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1112 : * device hardware or the driver software.
1113 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1114 : * @retval -errno Negative errno code on failure.
1115 : */
1116 1 : static inline int spi_write(const struct device *dev,
1117 : const struct spi_config *config,
1118 : const struct spi_buf_set *tx_bufs)
1119 : {
1120 : return spi_transceive(dev, config, tx_bufs, NULL);
1121 : }
1122 :
1123 : /**
1124 : * @brief Write data to a SPI bus specified in @p spi_dt_spec.
1125 : *
1126 : * This is equivalent to:
1127 : *
1128 : * spi_write(spec->bus, &spec->config, tx_bufs);
1129 : *
1130 : * @param spec SPI specification from devicetree
1131 : * @param tx_bufs Buffer array where data to be sent originates from.
1132 : *
1133 : * @return a value from spi_write().
1134 : */
1135 1 : static inline int spi_write_dt(const struct spi_dt_spec *spec,
1136 : const struct spi_buf_set *tx_bufs)
1137 : {
1138 : return spi_write(spec->bus, &spec->config, tx_bufs);
1139 : }
1140 : /** @} */
1141 :
1142 : #if defined(CONFIG_SPI_ASYNC) || defined(__DOXYGEN__)
1143 : /**
1144 : * @name SPI Asynchronous Transfer Functions
1145 : *
1146 : * With this API the transfer function will return after the transfer is started and
1147 : * report completion through a notification mechanism: callback or signal.
1148 : *
1149 : * @note Note that asynchronous API calls can still be blocking if the bus is already busy.
1150 : * The functions will block until the bus is available to start the requested transfer.
1151 : *
1152 : * @{
1153 : */
1154 :
1155 : /**
1156 : * @brief Read/write the specified amount of data from the SPI driver.
1157 : *
1158 : * @note This function is asynchronous.
1159 : *
1160 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1161 : * is selected.
1162 : *
1163 : * @note The chip select behavior as described by @ref spi_transceive and
1164 : * the function of controller/peripheral modes is the same.
1165 : *
1166 : * @param dev Pointer to the device structure for the driver instance
1167 : * @param config Pointer to a valid spi_config structure instance.
1168 : * Pointer-comparison may be used to detect changes from
1169 : * previous operations.
1170 : * @param tx_bufs Buffer array where data to be sent originates from,
1171 : * or NULL if none.
1172 : * @param rx_bufs Buffer array where data to be read will be written to,
1173 : * or NULL if none.
1174 : * @param callback Function pointer to completion callback.
1175 : * (Note: if NULL this function will not
1176 : * notify the end of the transaction, and whether it went
1177 : * successfully or not).
1178 : * @param userdata Userdata passed to callback
1179 : *
1180 : * @retval frames Positive number of frames received in slave mode.
1181 : * @retval 0 If successful in master mode.
1182 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1183 : * device hardware or the driver software.
1184 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1185 : * @retval -errno Negative errno code on failure.
1186 : */
1187 1 : static inline int spi_transceive_cb(const struct device *dev,
1188 : const struct spi_config *config,
1189 : const struct spi_buf_set *tx_bufs,
1190 : const struct spi_buf_set *rx_bufs,
1191 : spi_callback_t callback,
1192 : void *userdata)
1193 : {
1194 : const struct spi_driver_api *api =
1195 : (const struct spi_driver_api *)dev->api;
1196 :
1197 : return api->transceive_async(dev, config, tx_bufs, rx_bufs, callback, userdata);
1198 : }
1199 :
1200 : #if defined(CONFIG_POLL) || defined(__DOXYGEN__)
1201 :
1202 : /** @cond INTERNAL_HIDDEN */
1203 : void z_spi_transfer_signal_cb(const struct device *dev, int result, void *userdata);
1204 : /** @endcond */
1205 :
1206 : /**
1207 : * @brief Read/write the specified amount of data from the SPI driver.
1208 : *
1209 : * @note This function is asynchronous.
1210 : *
1211 : * @note The chip select behavior as described by @ref spi_transceive and
1212 : * the function of controller/peripheral modes is the same.
1213 : *
1214 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1215 : * and @kconfig{CONFIG_POLL} are selected.
1216 : *
1217 : * @param dev Pointer to the device structure for the driver instance
1218 : * @param config Pointer to a valid spi_config structure instance.
1219 : * Pointer-comparison may be used to detect changes from
1220 : * previous operations.
1221 : * @param tx_bufs Buffer array where data to be sent originates from,
1222 : * or NULL if none.
1223 : * @param rx_bufs Buffer array where data to be read will be written to,
1224 : * or NULL if none.
1225 : * @param sig A pointer to a valid and ready to be signaled
1226 : * struct k_poll_signal. (Note: if NULL this function will not
1227 : * notify the end of the transaction, and whether it went
1228 : * successfully or not).
1229 : *
1230 : * @retval frames Positive number of frames received in slave mode.
1231 : * @retval 0 If successful in master mode.
1232 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1233 : * device hardware or the driver software.
1234 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1235 : * @retval -errno Negative errno code on failure.
1236 : */
1237 1 : static inline int spi_transceive_signal(const struct device *dev,
1238 : const struct spi_config *config,
1239 : const struct spi_buf_set *tx_bufs,
1240 : const struct spi_buf_set *rx_bufs,
1241 : struct k_poll_signal *sig)
1242 : {
1243 : const struct spi_driver_api *api =
1244 : (const struct spi_driver_api *)dev->api;
1245 : spi_callback_t cb = (sig == NULL) ? NULL : z_spi_transfer_signal_cb;
1246 :
1247 : return api->transceive_async(dev, config, tx_bufs, rx_bufs, cb, sig);
1248 : }
1249 :
1250 : /**
1251 : * @brief Read the specified amount of data from the SPI driver.
1252 : *
1253 : * @note This function is asynchronous.
1254 : *
1255 : * @note This function is a helper function calling spi_transceive_signal.
1256 : *
1257 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1258 : * and @kconfig{CONFIG_POLL} are selected.
1259 : *
1260 : * @param dev Pointer to the device structure for the driver instance
1261 : * @param config Pointer to a valid spi_config structure instance.
1262 : * Pointer-comparison may be used to detect changes from
1263 : * previous operations.
1264 : * @param rx_bufs Buffer array where data to be read will be written to.
1265 : * @param sig A pointer to a valid and ready to be signaled
1266 : * struct k_poll_signal. (Note: if NULL this function will not
1267 : * notify the end of the transaction, and whether it went
1268 : * successfully or not).
1269 : *
1270 : * @retval frames Positive number of frames received in slave mode.
1271 : * @retval 0 If successful
1272 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1273 : * device hardware or the driver software.
1274 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1275 : * @retval -errno Negative errno code on failure.
1276 : */
1277 1 : static inline int spi_read_signal(const struct device *dev,
1278 : const struct spi_config *config,
1279 : const struct spi_buf_set *rx_bufs,
1280 : struct k_poll_signal *sig)
1281 : {
1282 : return spi_transceive_signal(dev, config, NULL, rx_bufs, sig);
1283 : }
1284 :
1285 : /**
1286 : * @brief Write the specified amount of data from the SPI driver.
1287 : *
1288 : * @note This function is asynchronous.
1289 : *
1290 : * @note This function is a helper function calling spi_transceive_signal.
1291 : *
1292 : * @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
1293 : * and @kconfig{CONFIG_POLL} are selected.
1294 : *
1295 : * @param dev Pointer to the device structure for the driver instance
1296 : * @param config Pointer to a valid spi_config structure instance.
1297 : * Pointer-comparison may be used to detect changes from
1298 : * previous operations.
1299 : * @param tx_bufs Buffer array where data to be sent originates from.
1300 : * @param sig A pointer to a valid and ready to be signaled
1301 : * struct k_poll_signal. (Note: if NULL this function will not
1302 : * notify the end of the transaction, and whether it went
1303 : * successfully or not).
1304 : *
1305 : * @retval 0 If successful.
1306 : * @retval -ENOTSUP means some part of the spi config is not supported either by the
1307 : * device hardware or the driver software.
1308 : * @retval -EINVAL means that some parameter of the spi_config is invalid.
1309 : * @retval -errno Negative errno code on failure.
1310 : */
1311 1 : static inline int spi_write_signal(const struct device *dev,
1312 : const struct spi_config *config,
1313 : const struct spi_buf_set *tx_bufs,
1314 : struct k_poll_signal *sig)
1315 : {
1316 : return spi_transceive_signal(dev, config, tx_bufs, NULL, sig);
1317 : }
1318 :
1319 : #endif /* CONFIG_POLL */
1320 :
1321 : /** @} */
1322 : #endif /* CONFIG_SPI_ASYNC */
1323 :
1324 :
1325 : #if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)
1326 :
1327 : /**
1328 : * @name SPI RTIO API
1329 : *
1330 : * Theses functions are for using the SPI driver class through an RTIO-based API
1331 : *
1332 : * @{
1333 : */
1334 : /**
1335 : * @brief Submit a SPI device with a request
1336 : *
1337 : * @param iodev_sqe Prepared submissions queue entry connected to an iodev
1338 : * defined by SPI_IODEV_DEFINE.
1339 : * Must live as long as the request is in flight.
1340 : */
1341 1 : static inline void spi_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
1342 : {
1343 : const struct spi_dt_spec *dt_spec = (const struct spi_dt_spec *)iodev_sqe->sqe.iodev->data;
1344 : const struct device *dev = dt_spec->bus;
1345 : const struct spi_driver_api *api = (const struct spi_driver_api *)dev->api;
1346 :
1347 : api->iodev_submit(dt_spec->bus, iodev_sqe);
1348 : }
1349 :
1350 : /** @cond INTERNAL_HIDDEN */
1351 : extern const struct rtio_iodev_api spi_iodev_api;
1352 : /** @endcond */
1353 :
1354 : /**
1355 : * @brief Define an iodev for a given dt node on the bus
1356 : *
1357 : * These do not need to be shared globally but doing so
1358 : * will save a small amount of memory.
1359 : *
1360 : * @param name Symbolic name to use for defining the iodev
1361 : * @param node_id Devicetree node identifier
1362 : * @param operation_ SPI operational mode
1363 : */
1364 1 : #define SPI_DT_IODEV_DEFINE(name, node_id, operation_, ...) \
1365 : const struct spi_dt_spec _spi_dt_spec_##name = \
1366 : SPI_DT_SPEC_GET(node_id, operation_, __VA_ARGS__); \
1367 : RTIO_IODEV_DEFINE(name, &spi_iodev_api, (void *)&_spi_dt_spec_##name)
1368 :
1369 : /**
1370 : * @brief Validate that SPI bus (and CS gpio if defined) is ready.
1371 : *
1372 : * @param spi_iodev SPI iodev defined with SPI_DT_IODEV_DEFINE
1373 : *
1374 : * @retval true if the SPI bus is ready for use.
1375 : * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
1376 : */
1377 1 : static inline bool spi_is_ready_iodev(const struct rtio_iodev *spi_iodev)
1378 : {
1379 : struct spi_dt_spec *spec = (struct spi_dt_spec *)spi_iodev->data;
1380 :
1381 : return spi_is_ready_dt(spec);
1382 : }
1383 : /** @} */
1384 :
1385 : #endif /* CONFIG_SPI_RTIO */
1386 :
1387 : /**
1388 : * @brief Release the SPI device locked on and/or the CS by the current config
1389 : *
1390 : * Note: This synchronous function is used to release either the lock on the
1391 : * SPI device and/or the CS line that was kept if, and if only,
1392 : * given config parameter was the last one to be used (in any of the
1393 : * above functions) and if it has the SPI_LOCK_ON bit set and/or the
1394 : * SPI_HOLD_ON_CS bit set into its operation bits field.
1395 : * This can be used if the caller needs to keep its hand on the SPI
1396 : * device for consecutive transactions and/or if it needs the device to
1397 : * stay selected. Usually both bits will be used along each other, so the
1398 : * the device is locked and stays on until another operation is necessary
1399 : * or until it gets released with the present function.
1400 : *
1401 : * @param dev Pointer to the device structure for the driver instance
1402 : * @param config Pointer to a valid spi_config structure instance.
1403 : *
1404 : * @retval 0 If successful.
1405 : * @retval -errno Negative errno code on failure.
1406 : */
1407 1 : __syscall int spi_release(const struct device *dev,
1408 : const struct spi_config *config);
1409 :
1410 : static inline int z_impl_spi_release(const struct device *dev,
1411 : const struct spi_config *config)
1412 : {
1413 : const struct spi_driver_api *api =
1414 : (const struct spi_driver_api *)dev->api;
1415 :
1416 : return api->release(dev, config);
1417 : }
1418 :
1419 : /**
1420 : * @brief Release the SPI device specified in @p spi_dt_spec.
1421 : *
1422 : * This is equivalent to:
1423 : *
1424 : * spi_release(spec->bus, &spec->config);
1425 : *
1426 : * @param spec SPI specification from devicetree
1427 : *
1428 : * @return a value from spi_release().
1429 : */
1430 1 : static inline int spi_release_dt(const struct spi_dt_spec *spec)
1431 : {
1432 : return spi_release(spec->bus, &spec->config);
1433 : }
1434 :
1435 : #ifdef __cplusplus
1436 : }
1437 : #endif
1438 :
1439 : /**
1440 : * @}
1441 : */
1442 :
1443 : #include <zephyr/syscalls/spi.h>
1444 :
1445 : /**
1446 : * @}
1447 : */
1448 : #endif /* ZEPHYR_INCLUDE_DRIVERS_SPI_H_ */
|
