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 : /**
22 : * @defgroup swdp_interface SWDP Interface
23 : * @since 3.7
24 : * @version 0.1.0
25 : * @ingroup io_interfaces
26 : * @{
27 : */
28 :
29 : /**
30 : * @name SWD Packet Request Bits
31 : *
32 : * Bit definitions for SWD packet request fields.
33 : * These bits are used to construct the 8-bit request packet header sent during an SWD transaction.
34 : *
35 : * @{
36 : */
37 :
38 : /** Access Port (AP) or Debug Port (DP). 1 = AP, 0 = DP */
39 1 : #define SWDP_REQUEST_APnDP BIT(0)
40 : /** Read (1) or Write (0) operation */
41 1 : #define SWDP_REQUEST_RnW BIT(1)
42 : /** Address bit 2 for register selection */
43 1 : #define SWDP_REQUEST_A2 BIT(2)
44 : /** Address bit 3 for register selection */
45 1 : #define SWDP_REQUEST_A3 BIT(3)
46 :
47 : /** @} */
48 :
49 : /**
50 : * @name SWD Acknowledge (ACK) Response Bits
51 : *
52 : * Bit definitions for SWD acknowledge response fields.
53 : * These bits are used to indicate the result of an SWD transaction.
54 : *
55 : * @{
56 : */
57 :
58 : /** Transaction completed successfully */
59 1 : #define SWDP_ACK_OK BIT(0)
60 : /** Target requests to retry the transaction later */
61 1 : #define SWDP_ACK_WAIT BIT(1)
62 : /** Target detected a fault condition */
63 1 : #define SWDP_ACK_FAULT BIT(2)
64 :
65 : /** @} */
66 :
67 : /** Transfer or parity error detected during transaction */
68 1 : #define SWDP_TRANSFER_ERROR BIT(3)
69 :
70 : /**
71 : * @name SWDP Interface Pin Definitions
72 : *
73 : * Pin identifiers for SWDP interface control.
74 : * These constants define bit positions for controlling individual pins in the SWDP interface.
75 : *
76 : * @{
77 : */
78 :
79 : /** Serial Wire Clock (SWCLK) pin identifier */
80 1 : #define SWDP_SWCLK_PIN 0U
81 : /** Serial Wire Data Input/Output (SWDIO) pin identifier */
82 1 : #define SWDP_SWDIO_PIN 1U
83 : /** Active-low reset (nRESET) pin identifier */
84 1 : #define SWDP_nRESET_PIN 7U
85 :
86 : /** @} */
87 :
88 : /**
89 : * Serial Wire Debug Port (SWDP) driver API.
90 : * This is the mandatory API any Serial Wire Debug Port driver needs to expose.
91 : */
92 1 : struct swdp_api {
93 : /**
94 : * @brief Write count bits to SWDIO from data LSB first
95 : *
96 : * @param dev SWDP device
97 : * @param count Number of bits to write
98 : * @param data Bits to write
99 : * @return 0 on success, or error code
100 : */
101 1 : int (*swdp_output_sequence)(const struct device *dev,
102 : uint32_t count,
103 : const uint8_t *data);
104 :
105 : /**
106 : * @brief Read count bits from SWDIO into data LSB first
107 : *
108 : * @param dev SWDP device
109 : * @param count Number of bits to read
110 : * @param data Buffer to store bits read
111 : * @return 0 on success, or error code
112 : */
113 1 : int (*swdp_input_sequence)(const struct device *dev,
114 : uint32_t count,
115 : uint8_t *data);
116 :
117 : /**
118 : * @brief Perform SWDP transfer and store response
119 : *
120 : * @param dev SWDP device
121 : * @param request SWDP request bits
122 : * @param data Data to be transferred with request
123 : * @param idle_cycles Idle cycles between request and response
124 : * @param response Buffer to store response (ACK/WAIT/FAULT)
125 : * @return 0 on success, or error code
126 : */
127 1 : int (*swdp_transfer)(const struct device *dev,
128 : uint8_t request,
129 : uint32_t *data,
130 : uint8_t idle_cycles,
131 : uint8_t *response);
132 :
133 : /**
134 : * @brief Set SWCLK, SWDPIO, and nRESET pins state
135 : * @note The bit positions are defined by the SWDP_*_PIN macros.
136 : *
137 : * @param dev SWDP device
138 : * @param pins Bitmask of pins to set
139 : * @param value Value to set pins to
140 : * @return 0 on success, or error code
141 : */
142 1 : int (*swdp_set_pins)(const struct device *dev,
143 : uint8_t pins, uint8_t value);
144 :
145 : /**
146 : * @brief Get SWCLK, SWDPIO, and nRESET pins state
147 : * @note The bit positions are defined by the SWDP_*_PIN macros.
148 : *
149 : * @param dev SWDP device
150 : * @param state Place to store pins state
151 : * @return 0 on success, or error code
152 : */
153 1 : int (*swdp_get_pins)(const struct device *dev, uint8_t *state);
154 :
155 : /**
156 : * @brief Set SWDP clock frequency
157 : *
158 : * @param dev SWDP device
159 : * @param clock Clock frequency in Hz
160 : * @return 0 on success, or error code
161 : */
162 1 : int (*swdp_set_clock)(const struct device *dev, uint32_t clock);
163 :
164 : /**
165 : * @brief Configure SWDP interface
166 : *
167 : * @param dev SWDP device
168 : * @param turnaround Line turnaround cycles
169 : * @param data_phase Always generate Data Phase (also on WAIT/FAULT)
170 : * @return 0 on success, or error code
171 : */
172 1 : int (*swdp_configure)(const struct device *dev,
173 : uint8_t turnaround,
174 : bool data_phase);
175 :
176 : /**
177 : * @brief Enable interface, set pins to default state
178 : *
179 : * @note SWDPIO is set to output mode, SWCLK and nRESET are set to high level.
180 : *
181 : * @param dev SWDP device
182 : * @return 0 on success, or error code
183 : */
184 1 : int (*swdp_port_on)(const struct device *dev);
185 :
186 : /**
187 : * @brief Disable interface, set pins to High-Z mode
188 : *
189 : * @param dev SWDP device
190 : * @return 0 on success, or error code
191 : */
192 1 : int (*swdp_port_off)(const struct device *dev);
193 : };
194 :
195 : #ifdef __cplusplus
196 : }
197 : #endif
198 :
199 : /** @} */
200 :
201 : #endif /* ZEPHYR_INCLUDE_SWDP_H_ */
|
