libxr
Embedded C++ framework for bare-metal, RTOS and Linux
Loading...
Searching...
No Matches
Classes | Public Member Functions | List of all members
LibXR::Debug::Swd Class Referenceabstract

SWD 探针抽象基类，提供链路控制、传输与 DP/AP 辅助接口。 Abstract SWD probe base class providing link control, transfer, and DP/AP helpers. More...

#include <swd.hpp>

Inheritance diagram for LibXR::Debug::Swd:
[legend]

Classes

struct  TransferPolicy
 传输策略（WAIT 重试与空闲周期插入）。 Transfer policy (WAIT retry & idle insertion). More...
 

Public Member Functions

virtual ~Swd ()=default
 虚析构函数 / Virtual destructor.
 
 Swd (const Swd &)=delete
 
Swd & operator= (const Swd &)=delete
 
void SetTransferPolicy (const TransferPolicy &policy)
 设置传输策略 / Set transfer policy.
 
const TransferPolicy & GetTransferPolicy () const
 获取传输策略 / Get transfer policy.
 
virtual ErrorCode SetClockHz (uint32_t hz)=0
 设置 SWCLK 频率（可选） / Set SWCLK frequency (optional).
 
virtual void Close ()=0
 关闭探针并释放资源 / Close probe and release resources.
 
virtual ErrorCode LineReset ()=0
 执行 SWD 线复位 / Perform SWD line reset.
 
virtual ErrorCode EnterSwd ()=0
 进入 SWD 模式（如需从 JTAG 切换）。 Enter SWD mode (e.g., switch from JTAG if needed).
 
virtual ErrorCode Transfer (const SwdProtocol::Request &req, SwdProtocol::Response &resp)=0
 执行一次 SWD 传输（不含重试） / Perform one SWD transfer (no retry).
 
ErrorCode TransferWithRetry (const SwdProtocol::Request &req, SwdProtocol::Response &resp)
 带重试的 SWD 传输封装（WAIT 重试 + IdleCycles 插入）。 SWD transfer wrapper with retry (WAIT retry + IdleCycles insertion).
 
ErrorCode DpRead (SwdProtocol::DpReadReg reg, uint32_t &val, SwdProtocol::Ack &ack)
 DP 寄存器读取（无重试） / DP register read (no retry).
 
ErrorCode DpWrite (SwdProtocol::DpWriteReg reg, uint32_t val, SwdProtocol::Ack &ack)
 DP 寄存器写入（无重试） / DP register write (no retry).
 
ErrorCode DpReadTxn (SwdProtocol::DpReadReg reg, uint32_t &val, SwdProtocol::Ack &ack)
 DP 读事务（带重试） / DP read transaction (with retry).
 
ErrorCode DpWriteTxn (SwdProtocol::DpWriteReg reg, uint32_t val, SwdProtocol::Ack &ack)
 DP 写事务（带重试） / DP write transaction (with retry).
 
ErrorCode ApReadTxn (uint8_t addr2b, uint32_t &val, SwdProtocol::Ack &ack)
 AP 读事务（带重试，包含 RDBUFF 回读）。 AP read transaction (with retry, with RDBUFF readback).
 
ErrorCode ApReadPostedTxn (uint8_t addr2b, uint32_t &posted_val, SwdProtocol::Ack &ack)
 AP 读事务（带重试，不读 RDBUFF；返回 posted 数据）。 AP read transaction (with retry, no RDBUFF; returns posted data).
 
ErrorCode DpReadRdbuffTxn (uint32_t &val, SwdProtocol::Ack &ack)
 读取 DP RDBUFF（带重试） / Read DP RDBUFF (with retry).
 
ErrorCode ApWriteTxn (uint8_t addr2b, uint32_t val, SwdProtocol::Ack &ack)
 AP 写事务（带重试） / AP write transaction (with retry).
 
ErrorCode ReadIdCode (uint32_t &idcode, SwdProtocol::Ack &ack)
 读取 DP IDCODE / Read DP IDCODE.
 
ErrorCode WriteAbort (uint32_t flags, SwdProtocol::Ack &ack)
 写入 DP ABORT（无重试） / Write DP ABORT (no retry).
 
ErrorCode WriteAbortTxn (uint32_t flags, SwdProtocol::Ack &ack)
 写入 DP ABORT（带重试） / Write DP ABORT (with retry).
 
ErrorCode SetSelectCached (uint32_t select, SwdProtocol::Ack &ack)
 写 SELECT（带缓存；命中则跳过写入）。 Write SELECT with cache (skip write on hit).
 
void InvalidateSelectCache ()
 失效 SELECT 缓存 / Invalidate SELECT cache.
 
 Swd ()=default
 构造函数 / Constructor.
 
virtual void IdleClocks (uint32_t cycles)=0
 插入空闲时钟周期 / Insert idle clock cycles.
 
virtual ErrorCode SeqWriteBits (uint32_t cycles, const uint8_t *data_lsb_first)=0
 
virtual ErrorCode SeqReadBits (uint32_t cycles, uint8_t *out_lsb_first)=0
 

Detailed Description

SWD 探针抽象基类，提供链路控制、传输与 DP/AP 辅助接口。 Abstract SWD probe base class providing link control, transfer, and DP/AP helpers.

Definition at line 16 of file swd.hpp.

Member Function Documentation

◆ ApReadPostedTxn()

ErrorCode LibXR::Debug::Swd::ApReadPostedTxn ( uint8_t addr2b,
uint32_t & posted_val,
SwdProtocol::Ack & ack )
inline

AP 读事务（带重试，不读 RDBUFF；返回 posted 数据）。 AP read transaction (with retry, no RDBUFF; returns posted data).

Note
返回的 rdata 是上一笔 AP READ 结果（posted）。 The returned rdata is the previous AP READ result (posted). 调用方需额外读取一次 DP RDBUFF 以获得最后一次 AP READ 的真实数据。 Caller must read DP RDBUFF once to obtain the last AP READ value.
Parameters
addr2bAP 寄存器地址（A2/A3，两位） / AP register address (A2/A3, 2-bit).
posted_val输出：posted 数据 / Output: posted value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 306 of file swd.hpp.

307 {
308 SwdProtocol::Response resp;
309 const ErrorCode EC = TransferWithRetry(SwdProtocol::make_ap_read_req(addr2b), resp);
310 ack = resp.ack;
311
312 if (EC != ErrorCode::OK)
313 {
314 return EC;
315 }
316 if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
317 {
318 return ErrorCode::FAILED;
319 }
320
321 posted_val = resp.rdata;
322 return ErrorCode::OK;
323 }
LibXR::Debug::Swd::TransferWithRetry
ErrorCode TransferWithRetry(const SwdProtocol::Request &req, SwdProtocol::Response &resp)
带重试的 SWD 传输封装（WAIT 重试 + IdleCycles 插入）。 SWD transfer wrapper with retry (WAIT retry + IdleCycles inse...
Definition swd.hpp:110
LibXR::ErrorCode
ErrorCode
定义错误码枚举 / Defines an enumeration for error codes
Definition libxr_def.hpp:132
LibXR::ErrorCode::FAILED
@ FAILED
操作失败 / Operation failed
LibXR::ErrorCode::OK
@ OK
操作成功 / Operation successful

◆ ApReadTxn()

ErrorCode LibXR::Debug::Swd::ApReadTxn ( uint8_t addr2b,
uint32_t & val,
SwdProtocol::Ack & ack )
inline

AP 读事务（带重试，包含 RDBUFF 回读）。 AP read transaction (with retry, with RDBUFF readback).

注意：AP 读为 posted；该辅助函数执行：1) AP READ（获得 posted 数据）。2) 读取 DP RDBUFF 获取本次 AP READ 的实际数据。 Note: AP reads are posted; this helper performs: 1) AP READ (gets posted data). 2) DP RDBUFF read to obtain the actual data for this AP read.

Parameters
addr2bAP 寄存器地址（A2/A3，两位） / AP register address (A2/A3, 2-bit).
val输出：实际读取的数据 / Output: actual read value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 274 of file swd.hpp.

275 {
276 SwdProtocol::Response resp;
277 const ErrorCode EC = TransferWithRetry(SwdProtocol::make_ap_read_req(addr2b), resp);
278 ack = resp.ack;
279
280 if (EC != ErrorCode::OK)
281 {
282 return EC;
283 }
284 if (resp.ack != SwdProtocol::Ack::OK)
285 {
286 return ErrorCode::FAILED;
287 }
288
289 return DpReadTxn(SwdProtocol::DpReadReg::RDBUFF, val, ack);
290 }
LibXR::Debug::Swd::DpReadTxn
ErrorCode DpReadTxn(SwdProtocol::DpReadReg reg, uint32_t &val, SwdProtocol::Ack &ack)
DP 读事务（带重试） / DP read transaction (with retry).
Definition swd.hpp:218

◆ ApWriteTxn()

ErrorCode LibXR::Debug::Swd::ApWriteTxn ( uint8_t addr2b,
uint32_t val,
SwdProtocol::Ack & ack )
inline

AP 写事务（带重试） / AP write transaction (with retry).

Parameters
addr2bAP 寄存器地址（A2/A3，两位） / AP register address (A2/A3, 2-bit).
val写入数据 / Write value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 343 of file swd.hpp.

344 {
345 SwdProtocol::Response resp;
346 const ErrorCode EC =
347 TransferWithRetry(SwdProtocol::make_ap_write_req(addr2b, val), resp);
348 ack = resp.ack;
349
350 if (EC != ErrorCode::OK)
351 {
352 return EC;
353 }
354
355 return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
356 }

◆ Close()

virtual void LibXR::Debug::Swd::Close ( )
pure virtual

关闭探针并释放资源 / Close probe and release resources.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ DpRead()

ErrorCode LibXR::Debug::Swd::DpRead ( SwdProtocol::DpReadReg reg,
uint32_t & val,
SwdProtocol::Ack & ack )
inline

DP 寄存器读取（无重试） / DP register read (no retry).

Parameters
regDP 读寄存器 / DP read register.
val输出：读到的数据 / Output: read value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 169 of file swd.hpp.

170 {
171 SwdProtocol::Response resp;
172 const ErrorCode EC = Transfer(SwdProtocol::make_dp_read_req(reg), resp);
173 if (EC != ErrorCode::OK)
174 {
175 ack = SwdProtocol::Ack::PROTOCOL;
176 return EC;
177 }
178
179 ack = resp.ack;
180
181 if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
182 {
183 return ErrorCode::FAILED;
184 }
185
186 val = resp.rdata;
187 return ErrorCode::OK;
188 }
LibXR::Debug::Swd::Transfer
virtual ErrorCode Transfer(const SwdProtocol::Request &req, SwdProtocol::Response &resp)=0
执行一次 SWD 传输（不含重试） / Perform one SWD transfer (no retry).

◆ DpReadRdbuffTxn()

ErrorCode LibXR::Debug::Swd::DpReadRdbuffTxn ( uint32_t & val,
SwdProtocol::Ack & ack )
inline

读取 DP RDBUFF（带重试） / Read DP RDBUFF (with retry).

Parameters
val输出：读到的数据 / Output: read value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 331 of file swd.hpp.

332 {
333 return DpReadTxn(SwdProtocol::DpReadReg::RDBUFF, val, ack);
334 }

◆ DpReadTxn()

ErrorCode LibXR::Debug::Swd::DpReadTxn ( SwdProtocol::DpReadReg reg,
uint32_t & val,
SwdProtocol::Ack & ack )
inline

DP 读事务（带重试） / DP read transaction (with retry).

Parameters
regDP 读寄存器 / DP read register.
val输出：读到的数据 / Output: read value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 218 of file swd.hpp.

219 {
220 SwdProtocol::Response resp;
221 const ErrorCode EC = TransferWithRetry(SwdProtocol::make_dp_read_req(reg), resp);
222 ack = resp.ack;
223
224 if (EC != ErrorCode::OK)
225 {
226 return EC;
227 }
228
229 if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
230 {
231 return ErrorCode::FAILED;
232 }
233
234 val = resp.rdata;
235 return ErrorCode::OK;
236 }

◆ DpWrite()

ErrorCode LibXR::Debug::Swd::DpWrite ( SwdProtocol::DpWriteReg reg,
uint32_t val,
SwdProtocol::Ack & ack )
inline

DP 寄存器写入（无重试） / DP register write (no retry).

Parameters
regDP 写寄存器 / DP write register.
val写入数据 / Write value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 197 of file swd.hpp.

198 {
199 SwdProtocol::Response resp;
200 const ErrorCode EC = Transfer(SwdProtocol::make_dp_write_req(reg, val), resp);
201 if (EC != ErrorCode::OK)
202 {
203 ack = SwdProtocol::Ack::PROTOCOL;
204 return EC;
205 }
206
207 ack = resp.ack;
208 return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
209 }

◆ DpWriteTxn()

ErrorCode LibXR::Debug::Swd::DpWriteTxn ( SwdProtocol::DpWriteReg reg,
uint32_t val,
SwdProtocol::Ack & ack )
inline

DP 写事务（带重试） / DP write transaction (with retry).

Parameters
regDP 写寄存器 / DP write register.
val写入数据 / Write value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 245 of file swd.hpp.

246 {
247 SwdProtocol::Response resp;
248 const ErrorCode EC =
249 TransferWithRetry(SwdProtocol::make_dp_write_req(reg, val), resp);
250 ack = resp.ack;
251
252 if (EC != ErrorCode::OK)
253 {
254 return EC;
255 }
256
257 return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
258 }

◆ EnterSwd()

virtual ErrorCode LibXR::Debug::Swd::EnterSwd ( )
pure virtual

进入 SWD 模式（如需从 JTAG 切换）。 Enter SWD mode (e.g., switch from JTAG if needed).

Returns
ErrorCode 操作结果 / Error code.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ GetTransferPolicy()

const TransferPolicy & LibXR::Debug::Swd::GetTransferPolicy ( ) const
inlinenodiscard

获取传输策略 / Get transfer policy.

Definition at line 55 of file swd.hpp.

55{ return policy_; }

◆ IdleClocks()

virtual void LibXR::Debug::Swd::IdleClocks ( uint32_t cycles)
pure virtual

插入空闲时钟周期 / Insert idle clock cycles.

Parameters
cycles周期数 / Number of cycles.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ InvalidateSelectCache()

void LibXR::Debug::Swd::InvalidateSelectCache ( )
inline

失效 SELECT 缓存 / Invalidate SELECT cache.

Definition at line 422 of file swd.hpp.

423 {
424 select_valid_ = false;
425 select_cache_ = 0u;
426 }

◆ LineReset()

virtual ErrorCode LibXR::Debug::Swd::LineReset ( )
pure virtual

执行 SWD 线复位 / Perform SWD line reset.

Returns
ErrorCode 操作结果 / Error code.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ ReadIdCode()

ErrorCode LibXR::Debug::Swd::ReadIdCode ( uint32_t & idcode,
SwdProtocol::Ack & ack )
inline

读取 DP IDCODE / Read DP IDCODE.

Parameters
idcode输出：IDCODE / Output: IDCODE.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 364 of file swd.hpp.

365 {
366 return DpRead(SwdProtocol::DpReadReg::IDCODE, idcode, ack);
367 }
LibXR::Debug::Swd::DpRead
ErrorCode DpRead(SwdProtocol::DpReadReg reg, uint32_t &val, SwdProtocol::Ack &ack)
DP 寄存器读取（无重试） / DP register read (no retry).
Definition swd.hpp:169

◆ SetClockHz()

virtual ErrorCode LibXR::Debug::Swd::SetClockHz ( uint32_t hz)
pure virtual

设置 SWCLK 频率（可选） / Set SWCLK frequency (optional).

Parameters
hz目标频率（Hz） / Target frequency in Hz.
Returns
ErrorCode 操作结果 / Error code.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ SetSelectCached()

ErrorCode LibXR::Debug::Swd::SetSelectCached ( uint32_t select,
SwdProtocol::Ack & ack )
inline

写 SELECT（带缓存；命中则跳过写入）。 Write SELECT with cache (skip write on hit).

Parameters
selectSELECT 值 / SELECT value.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 402 of file swd.hpp.

403 {
404 if (select_valid_ && (select_cache_ == select))
405 {
406 ack = SwdProtocol::Ack::OK;
407 return ErrorCode::OK;
408 }
409
410 const ErrorCode EC = DpWriteTxn(SwdProtocol::DpWriteReg::SELECT, select, ack);
411 if (EC == ErrorCode::OK && ack == SwdProtocol::Ack::OK)
412 {
413 select_cache_ = select;
414 select_valid_ = true;
415 }
416 return EC;
417 }
LibXR::Debug::Swd::DpWriteTxn
ErrorCode DpWriteTxn(SwdProtocol::DpWriteReg reg, uint32_t val, SwdProtocol::Ack &ack)
DP 写事务（带重试） / DP write transaction (with retry).
Definition swd.hpp:245

◆ SetTransferPolicy()

void LibXR::Debug::Swd::SetTransferPolicy ( const TransferPolicy & policy)
inline

设置传输策略 / Set transfer policy.

Parameters
policy传输策略 / Transfer policy.

Definition at line 50 of file swd.hpp.

50{ policy_ = policy; }

◆ Transfer()

virtual ErrorCode LibXR::Debug::Swd::Transfer ( const SwdProtocol::Request & req,
SwdProtocol::Response & resp )
pure virtual

执行一次 SWD 传输（不含重试） / Perform one SWD transfer (no retry).

Parameters
req请求包 / Request.
resp响应包 / Response.
Returns
ErrorCode 总线级错误码 / Bus-level error code.

Implemented in LibXR::Debug::SwdGeneralGPIO< SwclkGpioType, SwdioGpioType, IO_DRIVE_MODE >.

◆ TransferWithRetry()

ErrorCode LibXR::Debug::Swd::TransferWithRetry ( const SwdProtocol::Request & req,
SwdProtocol::Response & resp )
inline

带重试的 SWD 传输封装（WAIT 重试 + IdleCycles 插入）。 SWD transfer wrapper with retry (WAIT retry + IdleCycles insertion).

规则 / Rules:

  • 每次传输尝试后均插入 idle_cycles（包括 WAIT 重试）。 Insert idle_cycles after EACH attempt (including WAIT retries).
  • WAIT 最多重试 wait_retry 次 / Retry WAIT up to wait_retry times.
  • 若 ACK==FAULT 且策略允许，则尝试清除 sticky 错误。 If ACK==FAULT and enabled, best-effort clear sticky errors.
Parameters
req请求包 / Request.
resp响应包 / Response.
Returns
ErrorCode 操作结果（传输流程级） / Error code (flow-level).

Definition at line 110 of file swd.hpp.

112 {
113 ResetResponse(resp);
114
115 uint32_t retries = 0;
116
117 while (true)
118 {
119 auto ec = Transfer(req, resp);
120 if (ec != ErrorCode::OK)
121 {
122 resp.ack = SwdProtocol::Ack::PROTOCOL;
123 InvalidateSelectCache();
124 return ec;
125 }
126
127 // CMSIS-DAP IdleCycles：每次传输尝试后插入。
128 // CMSIS-DAP IdleCycles: insert after EACH transfer attempt.
129 if (policy_.idle_cycles != 0u)
130 {
131 IdleClocks(policy_.idle_cycles);
132 }
133
134 if (resp.ack != SwdProtocol::Ack::WAIT)
135 {
136 break;
137 }
138 if (retries >= policy_.wait_retry)
139 {
140 break;
141 }
142 ++retries;
143 }
144
145 if (resp.ack != SwdProtocol::Ack::OK)
146 {
147 InvalidateSelectCache();
148 }
149
150 if (resp.ack == SwdProtocol::Ack::FAULT && policy_.clear_sticky_on_fault)
151 {
152 (void)ClearStickyErrors();
153 }
154
155 return ErrorCode::OK;
156 }
LibXR::Debug::Swd::InvalidateSelectCache
void InvalidateSelectCache()
失效 SELECT 缓存 / Invalidate SELECT cache.
Definition swd.hpp:422
LibXR::Debug::Swd::IdleClocks
virtual void IdleClocks(uint32_t cycles)=0
插入空闲时钟周期 / Insert idle clock cycles.
LibXR::Debug::Swd::TransferPolicy::idle_cycles
uint8_t idle_cycles
空闲周期数 / Idle cycles.
Definition swd.hpp:32
LibXR::Debug::Swd::TransferPolicy::clear_sticky_on_fault
bool clear_sticky_on_fault
FAULT 时清除 sticky 错误 / Clear sticky errors on FAULT.
Definition swd.hpp:34
LibXR::Debug::Swd::TransferPolicy::wait_retry
uint16_t wait_retry
WAIT 最大重试次数 / Maximum WAIT retries.
Definition swd.hpp:33

◆ WriteAbort()

ErrorCode LibXR::Debug::Swd::WriteAbort ( uint32_t flags,
SwdProtocol::Ack & ack )
inline

写入 DP ABORT（无重试） / Write DP ABORT (no retry).

Parameters
flagsABORT 标志位 / ABORT flags.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 375 of file swd.hpp.

376 {
377 return DpWrite(SwdProtocol::DpWriteReg::ABORT, flags, ack);
378 }
LibXR::Debug::Swd::DpWrite
ErrorCode DpWrite(SwdProtocol::DpWriteReg reg, uint32_t val, SwdProtocol::Ack &ack)
DP 寄存器写入（无重试） / DP register write (no retry).
Definition swd.hpp:197

◆ WriteAbortTxn()

ErrorCode LibXR::Debug::Swd::WriteAbortTxn ( uint32_t flags,
SwdProtocol::Ack & ack )
inline

写入 DP ABORT（带重试） / Write DP ABORT (with retry).

Parameters
flagsABORT 标志位 / ABORT flags.
ack输出：ACK / Output: ACK.
Returns
ErrorCode 操作结果 / Error code.

Definition at line 386 of file swd.hpp.

387 {
388 return DpWriteTxn(SwdProtocol::DpWriteReg::ABORT, flags, ack);
389 }
The documentation for this class was generated from the following file: