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