drivers: spi: document expectation on spi config parameter

Most if not all drivers use an internal function
spi_context_configured() to bypass reconfiguring the SPI peripheral
when nothing has changed.  That function determines change based on
comparing the struct spi_config pointer that was last used.  This does
not work if a user changes fields within the pointed-to structure.

Document that pointer comparison may be used to detect changes.

Signed-off-by: Peter Bigot <[email protected]>

Author: pabigot

include/drivers/spi.h

@@ -162,6 +162,11 @@ struct spi_cs_control {
  *
  * @note Only cs_hold and lock_on can be changed between consecutive
  * transceive call. Rest of the attributes are not meant to be tweaked.
+ *
+ * @warning Most drivers use pointer comparison to determine whether a
+ * passed configuration is different from one used in a previous
+ * transaction.  Changes to fields in the structure may not be
+ * detected.
  */
 struct spi_config {
 	uint32_t		frequency;
@@ -244,6 +249,8 @@ __subsystem struct spi_driver_api {
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param tx_bufs Buffer array where data to be sent originates from,
  *        or NULL if none.
  * @param rx_bufs Buffer array where data to be read will be written to,
@@ -276,6 +283,8 @@ static inline int z_impl_spi_transceive(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param rx_bufs Buffer array where data to be read will be written to.
  *
  * @retval 0 If successful, negative errno code otherwise.
@@ -296,6 +305,8 @@ static inline int spi_read(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param tx_bufs Buffer array where data to be sent originates from.
  *
  * @retval 0 If successful, negative errno code otherwise.
@@ -316,6 +327,8 @@ static inline int spi_write(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param tx_bufs Buffer array where data to be sent originates from,
  *        or NULL if none.
  * @param rx_bufs Buffer array where data to be read will be written to,
@@ -358,6 +371,8 @@ static inline int spi_transceive_async(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param rx_bufs Buffer array where data to be read will be written to.
  * @param async A pointer to a valid and ready to be signaled
  *        struct k_poll_signal. (Note: if NULL this function will not
@@ -383,6 +398,8 @@ static inline int spi_read_async(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  * @param tx_bufs Buffer array where data to be sent originates from.
  * @param async A pointer to a valid and ready to be signaled
  *        struct k_poll_signal. (Note: if NULL this function will not
@@ -413,6 +430,8 @@ static inline int spi_write_async(struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance
  * @param config Pointer to a valid spi_config structure instance.
+ *        Pointer-comparison may be used to detect changes from
+ *        previous operations.
  */
 __syscall int spi_release(struct device *dev,
 			  const struct spi_config *config);