include: drivers: spi.h: Get CS delay parameters from DT

The CS delay parameter did not make a distinction between the setup and
hold time of the CS, and also did not specify very fine control which
can be done usually by a native controller CS. So use the new nanosecond
DT properties to get the delay values and make distinction.

Add deprecation warning if consumer supplies the delay parameter and
make it still work the old way in that case for backward compatibility
following API lifecycle process.

Update driver API version to 1.1.0 due to this change

Signed-off-by: Declan Snyder <[email protected]>

Author: decsny

doc/releases/migration-guide-4.3.rst

@@ -81,6 +81,17 @@ Phy
   clock-reference. The selection directly depends on the value on OTGHSSEL (OTG_HS PHY kernel
   clock source selection) located in the RCC_CCIPR2 register.
 
+SPI
+===
+
+* The macros :c:macro:`SPI_CS_CONTROL_INIT` :c:macro:`SPI_CS_CONTROL_INIT_INST`,
+  :c:macro:`SPI_CONFIG_DT`, :c:macro:`SPI_CONFIG_DT_INST`, :c:macro:`SPI_DT_SPEC_GET`,
+  and :c:macro:`SPI_DT_SPEC_INST_GET` have been changed so that they do not need to be
+  provided a delay parameter anymore. This is because the timing parameters of a SPI peripheral
+  chip select should now be specified in DT with the
+  ``spi-cs-setup-delay-ns`` and ``spi-cs-hold-delay-ns`` properties.
+  (:github:`87427`).
+
 Sensors
 =======
 

doc/releases/release-notes-4.3.rst

@@ -62,6 +62,10 @@ Deprecated APIs and options
 ===========================
 
 * :dtcompatible:`maxim,ds3231` is deprecated in favor of :dtcompatible:`maxim,ds3231-rtc`.
+* Providing a third agument to :c:macro:`SPI_CONFIG_DT`, :c:macro:`SPI_CONFIG_DT_INST`,
+  :c:macro:`SPI_DT_SPEC_GET`, :c:macro:`SPI_DT_SPEC_INST_GET` is deprecated. Providing a
+  second argument to :c:macro:`SPI_CS_CONTROL_INIT` is deprecated. Use new DT properties
+  ``spi-cs-setup-delay-ns`` and ``spi-cs-hold-delay-ns`` to specify delay instead.
 
 * :c:enum:`bt_hci_bus` was deprecated as it was not used. :c:macro:`BT_DT_HCI_BUS_GET` should be
   used instead.

include/zephyr/drivers/mipi_dbi.h

@@ -67,6 +67,7 @@ extern "C" {
 							   DT_REG_ADDR_RAW(node_id), \
 							   {}),		\
 			.delay = (delay_),				\
+			.cs_is_gpio = true,				\
 		},							\
 	}
 

include/zephyr/drivers/spi.h

@@ -18,7 +18,7 @@
  *        controllers.
  * @defgroup spi_interface SPI
  * @since 1.0
- * @version 1.0.0
+ * @version 1.1.0
  * @ingroup io_interfaces
  * @{
  */
@@ -242,19 +242,38 @@ extern "C" {
  *
  */
 struct spi_cs_control {
-	/**
-	 * GPIO devicetree specification of CS GPIO.
-	 * The device pointer can be set to NULL to fully inhibit CS control if
-	 * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
-	 * equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct
-	 * spi_config.
-	 */
-	struct gpio_dt_spec gpio;
-	/**
-	 * Delay in microseconds to wait before starting the
-	 * transmission and before releasing the CS line.
-	 */
-	uint32_t delay;
+	union {
+		struct {
+			/**
+			 * GPIO devicetree specification of CS GPIO.
+			 * The device pointer can be set to NULL to fully inhibit CS control if
+			 * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
+			 * equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct
+			 * spi_config.
+			 */
+			struct gpio_dt_spec gpio;
+			/**
+			 * Delay in microseconds to wait before starting the
+			 * transmission and before releasing the CS line.
+			 */
+			uint32_t delay;
+		};
+		struct {
+			/**
+			 * CS enable lead time, i.e. how long should the CS be asserted
+			 * before the first clock. Specified in nanoseconds.
+			 */
+			uint32_t setup_ns;
+			/**
+			 * CS enable lag time, i.e. how long should the CS be asserted
+			 * after the last clock, before the CS de-asserts.
+			 * Specified in nanoseconds.
+			 */
+			uint32_t hold_ns;
+		};
+	};
+	/* To keep track of which form of this struct is valid */
+	bool cs_is_gpio;
 };
 
 /**
@@ -310,6 +329,26 @@ struct spi_cs_control {
 #define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
 	SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))
 
+/** @cond INTERNAL_HIDDEN */
+#define SPI_CS_CONTROL_MAX_DELAY(node_id)			\
+	MAX(DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0),	\
+	    DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0))
+
+
+#define SPI_CS_CONTROL_INIT_GPIO(node_id, ...)						\
+	.gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id),					\
+	.delay = COND_CODE_1(IS_EMPTY(__VA_ARGS__),					\
+			(DIV_ROUND_UP(SPI_CS_CONTROL_MAX_DELAY(node_id), 1000)),	\
+			(__VA_ARGS__))
+
+#define SPI_CS_CONTROL_INIT_NATIVE(node_id)						\
+	.setup_ns = DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0),			\
+	.hold_ns = DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0),
+
+#define SPI_DEPRECATE_DELAY_WARN							\
+	__WARN("Delay parameter in SPI DT macros is deprecated, use DT prop instead")
+/** @endcond */
+
 /**
  * @brief Initialize and get a pointer to a @p spi_cs_control from a
  *        devicetree node identifier
@@ -332,27 +371,34 @@ struct spi_cs_control {
  *
  * @code{.c}
  *     struct spi_cs_control ctrl =
- *             SPI_CS_CONTROL_INIT(DT_NODELABEL(spidev), 2);
+ *             SPI_CS_CONTROL_INIT(DT_NODELABEL(spidev));
  * @endcode
  *
- * This example is equivalent to:
+ * This example is roughly equivalent to:
  *
  * @code{.c}
  *     struct spi_cs_control ctrl = {
  *             .gpio = SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(spidev)),
- *             .delay = 2,
+ *             .delay = DT_PROP(node_id, cs_delay_ns) / 1000,
+ *             .cs_is_gpio = true,
  *     };
  * @endcode
  *
+ * For non-gpio CS, the idea is similar but the lead and lag fields of the cs struct
+ * will be populated instead.
+ *
  * @param node_id Devicetree node identifier for a device on a SPI bus
- * @param delay_ The @p delay field to set in the @p spi_cs_control
+ *
  * @return a pointer to the @p spi_cs_control structure
  */
-#define SPI_CS_CONTROL_INIT(node_id, delay_)			  \
-	{							  \
-		.gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id),	  \
-		.delay = (delay_),				  \
-	}
+#define SPI_CS_CONTROL_INIT(node_id, ...)					\
+{										\
+	COND_CODE_0(IS_EMPTY(__VA_ARGS__), (SPI_DEPRECATE_DELAY_WARN), ())	\
+	.cs_is_gpio = DT_SPI_DEV_HAS_CS_GPIOS(node_id),				\
+	COND_CODE_1(DT_SPI_DEV_HAS_CS_GPIOS(node_id),				\
+			(SPI_CS_CONTROL_INIT_GPIO(node_id, __VA_ARGS__)),	\
+			(SPI_CS_CONTROL_INIT_NATIVE(node_id)))			\
+}
 
 /**
  * @brief Get a pointer to a @p spi_cs_control from a devicetree node
@@ -364,11 +410,11 @@ struct spi_cs_control {
  * this macro.
  *
  * @param inst Devicetree node instance number
- * @param delay_ The @p delay field to set in the @p spi_cs_control
+ *
  * @return a pointer to the @p spi_cs_control structure
  */
-#define SPI_CS_CONTROL_INIT_INST(inst, delay_)		\
-	SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)
+#define SPI_CS_CONTROL_INIT_INST(inst)			\
+	SPI_CS_CONTROL_INIT(DT_DRV_INST(inst))
 
 /** @} */
 
@@ -432,10 +478,8 @@ struct spi_config {
  * @param node_id Devicetree node identifier for the SPI device whose
  *                struct spi_config to create an initializer for
  * @param operation_ the desired @p operation field in the struct spi_config
- * @param delay_ the desired @p delay field in the struct spi_config's
- *               spi_cs_control, if there is one
  */
-#define SPI_CONFIG_DT(node_id, operation_, delay_)			\
+#define SPI_CONFIG_DT(node_id, operation_, ...)				\
 	{								\
 		.frequency = DT_PROP(node_id, spi_max_frequency),	\
 		.operation = (operation_) |				\
@@ -445,22 +489,20 @@ struct spi_config {
 			COND_CODE_1(DT_PROP(node_id, spi_cpha), SPI_MODE_CPHA, (0)) |	\
 			COND_CODE_1(DT_PROP(node_id, spi_hold_cs), SPI_HOLD_ON_CS, (0)),	\
 		.slave = DT_REG_ADDR(node_id),				\
-		.cs = SPI_CS_CONTROL_INIT(node_id, delay_),		\
+		.cs = SPI_CS_CONTROL_INIT(node_id, __VA_ARGS__),	\
 	}
 
 /**
  * @brief Structure initializer for spi_config from devicetree instance
  *
  * This is equivalent to
- * <tt>SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)</tt>.
+ * <tt>SPI_CONFIG_DT(DT_DRV_INST(inst), operation_)</tt>.
  *
  * @param inst Devicetree instance number
  * @param operation_ the desired @p operation field in the struct spi_config
- * @param delay_ the desired @p delay field in the struct spi_config's
- *               spi_cs_control, if there is one
  */
-#define SPI_CONFIG_DT_INST(inst, operation_, delay_)	\
-	SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)
+#define SPI_CONFIG_DT_INST(inst, operation_, ...)		\
+	SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, __VA_ARGS__)
 
 /**
  * @brief Complete SPI DT information
@@ -486,28 +528,24 @@ struct spi_dt_spec {
  * @param node_id Devicetree node identifier for the SPI device whose
  *                struct spi_dt_spec to create an initializer for
  * @param operation_ the desired @p operation field in the struct spi_config
- * @param delay_ the desired @p delay field in the struct spi_config's
- *               spi_cs_control, if there is one
  */
-#define SPI_DT_SPEC_GET(node_id, operation_, delay_)		     \
-	{							     \
-		.bus = DEVICE_DT_GET(DT_BUS(node_id)),		     \
-		.config = SPI_CONFIG_DT(node_id, operation_, delay_) \
+#define SPI_DT_SPEC_GET(node_id, operation_, ...)				\
+	{									\
+		.bus = DEVICE_DT_GET(DT_BUS(node_id)),				\
+		.config = SPI_CONFIG_DT(node_id, operation_, __VA_ARGS__),	\
 	}
 
 /**
  * @brief Structure initializer for spi_dt_spec from devicetree instance
  *
  * This is equivalent to
- * <tt>SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)</tt>.
+ * <tt>SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_)</tt>.
  *
  * @param inst Devicetree instance number
  * @param operation_ the desired @p operation field in the struct spi_config
- * @param delay_ the desired @p delay field in the struct spi_config's
- *               spi_cs_control, if there is one
  */
-#define SPI_DT_SPEC_INST_GET(inst, operation_, delay_) \
-	SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)
+#define SPI_DT_SPEC_INST_GET(inst, operation_, ...) \
+	SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, __VA_ARGS__)
 
 /**
  * @brief Value that will never compare true with any valid overrun character
@@ -863,7 +901,7 @@ __subsystem struct spi_driver_api {
  */
 static inline bool spi_cs_is_gpio(const struct spi_config *config)
 {
-	return config->cs.gpio.port != NULL;
+	return config->cs.cs_is_gpio;
 }
 
 /**
@@ -1291,11 +1329,10 @@ extern const struct rtio_iodev_api spi_iodev_api;
  * @param name Symbolic name to use for defining the iodev
  * @param node_id Devicetree node identifier
  * @param operation_ SPI operational mode
- * @param delay_ Chip select delay in microseconds
  */
-#define SPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_)			\
+#define SPI_DT_IODEV_DEFINE(name, node_id, operation_)				\
 	const struct spi_dt_spec _spi_dt_spec_##name =				\
-		SPI_DT_SPEC_GET(node_id, operation_, delay_);			\
+		SPI_DT_SPEC_GET(node_id, operation_);				\
 	RTIO_IODEV_DEFINE(name, &spi_iodev_api, (void *)&_spi_dt_spec_##name)
 
 /**