diff --git a/components/hal/include/hal/spi_slave_hd_hal.h b/components/hal/include/hal/spi_slave_hd_hal.h
index 2a2f3bc357..099139cc01 100644
--- a/components/hal/include/hal/spi_slave_hd_hal.h
+++ b/components/hal/include/hal/spi_slave_hd_hal.h
@@ -266,6 +266,10 @@ int spi_slave_hd_hal_get_last_addr(spi_slave_hd_hal_context_t *hal);
 /**
  * @brief Return the finished TX transaction
  *
+ * @note This API is based on this assumption: the hardware behaviour of current transaction completion is only modified by the its own caller layer.
+ * This means if some other code changed the hardware behaviour (e.g. clear intr raw bit), or the caller call this API without noticing the HW behaviour,
+ * this API will go wrong.
+ *
  * @param hal            Context of the HAL layer
  * @param out_trans      Pointer to the caller-defined transaction
  * @return               1: Transaction is finished; 0: Transaction is not finished
@@ -275,6 +279,10 @@ bool spi_slave_hd_hal_get_tx_finished_trans(spi_slave_hd_hal_context_t *hal, voi
 /**
  * @brief Return the finished RX transaction
  *
+ * @note This API is based on this assumption: the hardware behaviour of current transaction completion is only modified by the its own caller layer.
+ * This means if some other code changed the hardware behaviour (e.g. clear intr raw bit), or the caller call this API without noticing the HW behaviour,
+ * this API will go wrong.
+ *
  * @param hal            Context of the HAL layer
  * @param out_trans      Pointer to the caller-defined transaction
  * @param out_len        Actual number of bytes of received data