Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2019 PHYTEC Messtechnik GmbH
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Serial Wire Debug Port interface driver API
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_SWDP_H_
      13             : #define ZEPHYR_INCLUDE_SWDP_H_
      14             : 
      15             : #include <zephyr/device.h>
      16             : 
      17             : #ifdef __cplusplus
      18             : extern "C" {
      19             : #endif
      20             : 
      21             : /* SWDP packet request bits */
      22           0 : #define SWDP_REQUEST_APnDP                      BIT(0)
      23           0 : #define SWDP_REQUEST_RnW                        BIT(1)
      24           0 : #define SWDP_REQUEST_A2                         BIT(2)
      25           0 : #define SWDP_REQUEST_A3                         BIT(3)
      26             : 
      27             : /* SWDP acknowledge response bits */
      28           0 : #define SWDP_ACK_OK                             BIT(0)
      29           0 : #define SWDP_ACK_WAIT                           BIT(1)
      30           0 : #define SWDP_ACK_FAULT                          BIT(2)
      31             : 
      32             : /* SWDP transfer or parity error */
      33           0 : #define SWDP_TRANSFER_ERROR                     BIT(3)
      34             : 
      35             : /* SWDP Interface pins */
      36           0 : #define SWDP_SWCLK_PIN                  0U
      37           0 : #define SWDP_SWDIO_PIN                  1U
      38           0 : #define SWDP_nRESET_PIN                 7U
      39             : 
      40             : /*
      41             :  * Serial Wire Interface (SWDP) driver API.
      42             :  * This is the mandatory API any Serial Wire driver needs to expose.
      43             :  */
      44           0 : struct swdp_api {
      45             :         /**
      46             :          * @brief Write count bits to SWDIO from data LSB first
      47             :          *
      48             :          * @param dev SWDP device
      49             :          * @param count Number of bits to write
      50             :          * @param data Bits to write
      51             :          * @return 0 on success, or error code
      52             :          */
      53           1 :         int (*swdp_output_sequence)(const struct device *dev,
      54             :                                     uint32_t count,
      55             :                                     const uint8_t *data);
      56             : 
      57             :         /**
      58             :          * @brief Read count bits from SWDIO into data LSB first
      59             :          *
      60             :          * @param dev SWDP device
      61             :          * @param count Number of bits to read
      62             :          * @param data Buffer to store bits read
      63             :          * @return 0 on success, or error code
      64             :          */
      65           1 :         int (*swdp_input_sequence)(const struct device *dev,
      66             :                                    uint32_t count,
      67             :                                    uint8_t *data);
      68             : 
      69             :         /**
      70             :          * @brief Perform SWDP transfer and store response
      71             :          *
      72             :          * @param dev SWDP device
      73             :          * @param request SWDP request bits
      74             :          * @param data Data to be transferred with request
      75             :          * @param idle_cycles Idle cycles between request and response
      76             :          * @param response Buffer to store response (ACK/WAIT/FAULT)
      77             :          * @return 0 on success, or error code
      78             :          */
      79           1 :         int (*swdp_transfer)(const struct device *dev,
      80             :                              uint8_t request,
      81             :                              uint32_t *data,
      82             :                              uint8_t idle_cycles,
      83             :                              uint8_t *response);
      84             : 
      85             :         /**
      86             :          * @brief Set SWCLK, SWDPIO, and nRESET pins state
      87             :          * @note The bit positions are defined by the SWDP_*_PIN macros.
      88             :          *
      89             :          * @param dev SWDP device
      90             :          * @param pins Bitmask of pins to set
      91             :          * @param value Value to set pins to
      92             :          * @return 0 on success, or error code
      93             :          */
      94           1 :         int (*swdp_set_pins)(const struct device *dev,
      95             :                              uint8_t pins, uint8_t value);
      96             : 
      97             :         /**
      98             :          * @brief Get SWCLK, SWDPIO, and nRESET pins state
      99             :          * @note The bit positions are defined by the SWDP_*_PIN macros.
     100             :          *
     101             :          * @param dev SWDP device
     102             :          * @param state Place to store pins state
     103             :          * @return 0 on success, or error code
     104             :          */
     105           1 :         int (*swdp_get_pins)(const struct device *dev, uint8_t *state);
     106             : 
     107             :         /**
     108             :          * @brief Set SWDP clock frequency
     109             :          *
     110             :          * @param dev SWDP device
     111             :          * @param clock Clock frequency in Hz
     112             :          * @return 0 on success, or error code
     113             :          */
     114           1 :         int (*swdp_set_clock)(const struct device *dev, uint32_t clock);
     115             : 
     116             :         /**
     117             :          * @brief Configure SWDP interface
     118             :          *
     119             :          * @param dev SWDP device
     120             :          * @param turnaround Line turnaround cycles
     121             :          * @param data_phase Always generate Data Phase (also on WAIT/FAULT)
     122             :          * @return 0 on success, or error code
     123             :          */
     124           1 :         int (*swdp_configure)(const struct device *dev,
     125             :                               uint8_t turnaround,
     126             :                               bool data_phase);
     127             : 
     128             :         /**
     129             :          * @brief Enable interface, set pins to default state
     130             :          *
     131             :          * @note SWDPIO is set to output mode, SWCLK and nRESET are set to high level.
     132             :          *
     133             :          * @param dev SWDP device
     134             :          * @return 0 on success, or error code
     135             :          */
     136           1 :         int (*swdp_port_on)(const struct device *dev);
     137             : 
     138             :         /**
     139             :          * @brief Disable interface, set pins to High-Z mode
     140             :          *
     141             :          * @param dev SWDP device
     142             :          * @return 0 on success, or error code
     143             :          */
     144           1 :         int (*swdp_port_off)(const struct device *dev);
     145             : };
     146             : 
     147             : #ifdef __cplusplus
     148             : }
     149             : #endif
     150             : 
     151             : #endif /* ZEPHYR_INCLUDE_SWDP_H_ */