From a4f73112198c30e09a19b21c779210ac834451a4 Mon Sep 17 00:00:00 2001
From: Maximilian Deubel <maximilian.deubel@nordicsemi.no>
Date: Fri, 24 May 2024 16:20:46 +0200
Subject: [PATCH] drivers: swdp: document API

This patch adds documentation for the SWDP API.

Signed-off-by: Maximilian Deubel <maximilian.deubel@nordicsemi.no>
Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no>
---
 include/zephyr/drivers/swdp.h | 84 ++++++++++++++++++++++++++++-------
 1 file changed, 69 insertions(+), 15 deletions(-)

diff --git a/include/zephyr/drivers/swdp.h b/include/zephyr/drivers/swdp.h
index c1f06e521510a2..d742280e883f96 100644
--- a/include/zephyr/drivers/swdp.h
+++ b/include/zephyr/drivers/swdp.h
@@ -42,19 +42,39 @@ extern "C" {
  * This is the mandatory API any Serial Wire driver needs to expose.
  */
 struct swdp_api {
-	/* Generate SWJ Sequence according to sequence bit count and bit data */
+	/**
+	 * @brief Write count bits to SWDIO from data LSB first
+	 *
+	 * @param dev SWDP device
+	 * @param count Number of bits to write
+	 * @param data Bits to write
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_output_sequence)(const struct device *dev,
 				    uint32_t count,
 				    const uint8_t *data);
 
-	/* Read count bits from SWDIO into data LSB first */
+	/**
+	 * @brief Read count bits from SWDIO into data LSB first
+	 *
+	 * @param dev SWDP device
+	 * @param count Number of bits to read
+	 * @param data Buffer to store bits read
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_input_sequence)(const struct device *dev,
 				   uint32_t count,
 				   uint8_t *data);
 
-	/*
-	 * Perform SWDP transfer based on host request value and store
-	 * acknowledge response bits ACK[0:2].
+	/**
+	 * @brief Perform SWDP transfer and store response
+	 *
+	 * @param dev SWDP device
+	 * @param request SWDP request bits
+	 * @param data Data to be transferred with request
+	 * @param idle_cycles Idle cycles between request and response
+	 * @param response Buffer to store response (ACK/WAIT/FAULT)
+	 * @return 0 on success, or error code
 	 */
 	int (*swdp_transfer)(const struct device *dev,
 			     uint8_t request,
@@ -62,31 +82,65 @@ struct swdp_api {
 			     uint8_t idle_cycles,
 			     uint8_t *response);
 
-	/* Set SWCLK, SWDPIO, and nRESET pins state */
+	/**
+	 * @brief Set SWCLK, SWDPIO, and nRESET pins state
+	 * @note The bit positions are defined by the SWDP_*_PIN macros.
+	 *
+	 * @param dev SWDP device
+	 * @param pins Bitmask of pins to set
+	 * @param value Value to set pins to
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_set_pins)(const struct device *dev,
 			     uint8_t pins, uint8_t value);
 
-	/* Get SWCLK, SWDPIO, and nRESET pins state */
+	/**
+	 * @brief Get SWCLK, SWDPIO, and nRESET pins state
+	 * @note The bit positions are defined by the SWDP_*_PIN macros.
+	 *
+	 * @param dev SWDP device
+	 * @param state Place to store pins state
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_get_pins)(const struct device *dev, uint8_t *state);
 
-	/* Set SWCLK frequency */
+	/**
+	 * @brief Set SWDP clock frequency
+	 *
+	 * @param dev SWDP device
+	 * @param clock Clock frequency in Hz
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_set_clock)(const struct device *dev, uint32_t clock);
 
-	/*
-	 * Configure interface, line turnaround and whether data phase is
-	 * forced after WAIN and FAULT response.
+	/**
+	 * @brief Configure SWDP interface
+	 *
+	 * @param dev SWDP device
+	 * @param turnaround Line turnaround cycles
+	 * @param data_phase Always generate Data Phase (also on WAIT/FAULT)
+	 * @return 0 on success, or error code
 	 */
 	int (*swdp_configure)(const struct device *dev,
 			      uint8_t turnaround,
 			      bool data_phase);
 
-	/*
-	 * Enable interface, set SWDPIO to output mode
-	 * and set SWCLK and nRESET to default high level.
+	/**
+	 * @brief Enable interface, set pins to default state
+	 *
+	 * @note SWDPIO is set to output mode, SWCLK and nRESET are set to high level.
+	 *
+	 * @param dev SWDP device
+	 * @return 0 on success, or error code
 	 */
 	int (*swdp_port_on)(const struct device *dev);
 
-	/* Disables interface, set SWCLK, SWDPIO, nRESET to High-Z mode. */
+	/**
+	 * @brief Disable interface, set pins to High-Z mode
+	 *
+	 * @param dev SWDP device
+	 * @return 0 on success, or error code
+	 */
 	int (*swdp_port_off)(const struct device *dev);
 };