fix[STM32][SPI]: preload receive-only dummy buffer

preload the actual HAL receive buffer with 0xFF for receive-only transfers
rename spi_dma_flag to spi_xfer_flags to match DMA and interrupt flags
clarify SPI async completion and transfer-mode comments
add Doxygen comments for STM32 SPI runtime structures and handlers

bsp/stm32/libraries/HAL_Drivers/drivers/drv_spi.h

@@ -9,6 +9,11 @@
  * 2026-04-16     wdfk-prog    Add SPI interrupt transfer mode scaffolding
  */
 
+/**
+ * @file drv_spi.h
+ * @brief STM32 SPI bus driver private definitions.
+ */
+
 #ifndef __DRV_SPI_H__
 #define __DRV_SPI_H__
 
@@ -19,12 +24,12 @@
 #include "drv_dma.h"
 #include <ipc/completion.h>
 
-/* hardware bus */
+/* Enable STM32 hardware SPI driver code when any SPI instance is selected. */
 #if defined(BSP_USING_SPI1) || defined(BSP_USING_SPI2) || defined(BSP_USING_SPI3) || defined(BSP_USING_SPI4) || defined(BSP_USING_SPI5) || defined(BSP_USING_SPI6)
 #define BSP_HARDWARE_SPI
 #endif
 
-/* POLL configuration visibility */
+/* Aggregate polling transfer configuration from per-instance Kconfig macros. */
 #if defined(BSP_SPI1_TX_USING_POLL) || defined(BSP_SPI2_TX_USING_POLL) || defined(BSP_SPI3_TX_USING_POLL) || defined(BSP_SPI4_TX_USING_POLL) || defined(BSP_SPI5_TX_USING_POLL) || defined(BSP_SPI6_TX_USING_POLL)
 #define BSP_SPI_TX_USING_POLL
 #endif
@@ -61,7 +66,7 @@
 #define BSP_SPI_USING_POLL
 #endif
 
-/* DMA */
+/* Aggregate DMA transfer configuration from per-instance Kconfig macros. */
 #if defined(BSP_SPI1_TX_USING_DMA) || defined(BSP_SPI2_TX_USING_DMA) || defined(BSP_SPI3_TX_USING_DMA) || defined(BSP_SPI4_TX_USING_DMA) || defined(BSP_SPI5_TX_USING_DMA) || defined(BSP_SPI6_TX_USING_DMA)
 #define BSP_SPI_TX_USING_DMA
 #endif
@@ -98,7 +103,7 @@
 #define BSP_SPI_USING_DMA
 #endif
 
-/* INT */
+/* Aggregate interrupt transfer configuration from per-instance Kconfig macros. */
 #if defined(BSP_SPI1_TX_USING_INT) || defined(BSP_SPI2_TX_USING_INT) || defined(BSP_SPI3_TX_USING_INT) || defined(BSP_SPI4_TX_USING_INT) || defined(BSP_SPI5_TX_USING_INT) || defined(BSP_SPI6_TX_USING_INT)
 #define BSP_SPI_TX_USING_INT
 #endif
@@ -135,6 +140,7 @@
 #define BSP_SPI_USING_INT
 #endif
 
+/* Aggregate IRQ requirements from DMA and interrupt transfer modes. */
 #if defined(BSP_SPI1_USING_DMA) || defined(BSP_SPI1_USING_INT)
 #define BSP_SPI1_USING_IRQ
 #endif
@@ -163,59 +169,81 @@
 #define BSP_SPI_USING_IRQ
 #endif
 
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @brief Attach an SPI device to a registered STM32 SPI bus.
+ *
+ * @param bus_name SPI bus name, such as "spi1".
+ * @param device_name SPI device name to register.
+ * @param cs_pin Chip-select pin used by the SPI device.
+ * @return RT_EOK on success, otherwise an RT-Thread error code.
+ */
 rt_err_t rt_hw_spi_device_attach(const char *bus_name, const char *device_name, rt_base_t cs_pin);
+
+/**
+ * @brief Detach a previously attached STM32 SPI device.
+ *
+ * @param device_name SPI device name to detach.
+ * @return RT_EOK on success, otherwise an RT-Thread error code.
+ */
 rt_err_t rt_hw_spi_device_detach(const char *device_name);
 
 #ifdef __cplusplus
 }
 #endif
 
+/**
+ * @brief Static configuration for one STM32 SPI bus instance.
+ */
 struct stm32_spi_config
 {
-    SPI_TypeDef *Instance;
-    char *bus_name;
-    IRQn_Type irq_type;
+    SPI_TypeDef *Instance;     /**< SPI peripheral register base. */
+    char *bus_name;            /**< RT-Thread SPI bus name. */
+    IRQn_Type irq_type;        /**< SPI peripheral IRQ number. */
 #ifdef BSP_SPI_RX_USING_DMA
-    const struct stm32_dma_config *dma_rx;
+    const struct stm32_dma_config *dma_rx; /**< RX DMA configuration. */
 #endif /* BSP_SPI_RX_USING_DMA */
 #ifdef BSP_SPI_TX_USING_DMA
-    const struct stm32_dma_config *dma_tx;
+    const struct stm32_dma_config *dma_tx; /**< TX DMA configuration. */
 #endif /* BSP_SPI_TX_USING_DMA */
 };
 
+/**
+ * @brief Board-level SPI device attachment information.
+ */
 struct stm32_spi_device
 {
-    rt_uint32_t pin;
-    char *bus_name;
-    char *device_name;
+    rt_uint32_t pin;    /**< Chip-select pin number. */
+    char *bus_name;     /**< SPI bus name used for attachment. */
+    char *device_name;  /**< SPI device name registered on the bus. */
 };
 
-/* stm32 spi dirver class */
+/**
+ * @brief Runtime context for one STM32 SPI bus.
+ */
 struct stm32_spi
 {
-    SPI_HandleTypeDef handle;
-    struct stm32_spi_config *config;
-    struct rt_spi_configuration *cfg;
-    struct rt_spi_bus spi_bus;
-    rt_uint16_t spi_dma_flag;
+    SPI_HandleTypeDef handle;          /**< STM32 HAL SPI handle. */
+    struct stm32_spi_config *config;   /**< Static bus configuration. */
+    struct rt_spi_configuration *cfg;  /**< Active RT-Thread SPI configuration. */
+    struct rt_spi_bus spi_bus;         /**< RT-Thread SPI bus object. */
+    rt_uint16_t spi_xfer_flags;        /**< RT_DEVICE_FLAG_DMA_* and RT_DEVICE_FLAG_INT_* transfer flags. */
 #ifdef BSP_SPI_USING_IRQ
-    struct rt_completion cpt;
+    struct rt_completion cpt;          /**< Completion used by asynchronous SPI transfers. */
 #endif /* BSP_SPI_USING_IRQ */
 #ifdef BSP_SPI_USING_DMA
     struct
     {
 #ifdef BSP_SPI_RX_USING_DMA
-        DMA_HandleTypeDef handle_rx;
+        DMA_HandleTypeDef handle_rx;   /**< STM32 HAL RX DMA handle. */
 #endif /* BSP_SPI_RX_USING_DMA */
 #ifdef BSP_SPI_TX_USING_DMA
-        DMA_HandleTypeDef handle_tx;
+        DMA_HandleTypeDef handle_tx;   /**< STM32 HAL TX DMA handle. */
 #endif /* BSP_SPI_TX_USING_DMA */
-    } dma;
+    } dma;                             /**< DMA handles associated with this SPI bus. */
 #endif /* BSP_SPI_USING_DMA */
 };