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]

Collaboration diagram for LibXR::Debug::Swd:

[legend]

Data Structures
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

Private Member Functions
ErrorCode	ClearStickyErrors ()
	清除 DP sticky 错误（尽力而为）。Clear DP sticky errors (best-effort).

Static Private Member Functions
static void	ResetResponse (SwdProtocol::Response &resp)
	重置响应结构体为默认值。Reset response to defaults.

Private Attributes
TransferPolicy	policy_ {}
	传输策略。Transfer policy.

uint32_t	select_cache_ = 0u
	SELECT 缓存值。SELECT cached value.

bool	select_valid_ = false
	SELECT 缓存是否有效。SELECT cache valid.

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

addr2b	AP 寄存器地址（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.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC = TransferWithRetry(SwdProtocol::make_ap_read_req(addr2b), resp);
    ack = resp.ack;
 
    if (EC != ErrorCode::OK)
    {
      return EC;
    }
    if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
    {
      return ErrorCode::FAILED;
    }
 
    posted_val = resp.rdata;
    return ErrorCode::OK;
  }

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

Parameters

addr2b	AP 寄存器地址（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.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC = TransferWithRetry(SwdProtocol::make_ap_read_req(addr2b), resp);
    ack = resp.ack;
 
    if (EC != ErrorCode::OK)
    {
      return EC;
    }
    if (resp.ack != SwdProtocol::Ack::OK)
    {
      return ErrorCode::FAILED;
    }
 
    return DpReadTxn(SwdProtocol::DpReadReg::RDBUFF, val, ack);
  }

◆ ApWriteTxn()

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

inline

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

Parameters

addr2b	AP 寄存器地址（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.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC =
        TransferWithRetry(SwdProtocol::make_ap_write_req(addr2b, val), resp);
    ack = resp.ack;
 
    if (EC != ErrorCode::OK)
    {
      return EC;
    }
 
    return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
  }

◆ ClearStickyErrors()

ErrorCode LibXR::Debug::Swd::ClearStickyErrors ( )

inlineprivate

清除 DP sticky 错误（尽力而为）。Clear DP sticky errors (best-effort).

Returns: ErrorCode 操作结果。Error code.

Definition at line 464 of file swd.hpp.

  {
    SwdProtocol::Ack ack = SwdProtocol::Ack::NO_ACK;
    const uint32_t FLAGS =
        SwdProtocol::DP_ABORT_STKCMPCLR | SwdProtocol::DP_ABORT_STKERRCLR |
        SwdProtocol::DP_ABORT_WDERRCLR | SwdProtocol::DP_ABORT_ORUNERRCLR;
    return DpWrite(SwdProtocol::DpWriteReg::ABORT, FLAGS, ack);
  }

◆ Close()

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

pure virtual

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

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

◆ DpRead()

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

inline

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

Parameters

reg	DP 读寄存器。DP read register.
val	输出：读到的数据。Output: read value.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 169 of file swd.hpp.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC = Transfer(SwdProtocol::make_dp_read_req(reg), resp);
    if (EC != ErrorCode::OK)
    {
      ack = SwdProtocol::Ack::PROTOCOL;
      return EC;
    }
 
    ack = resp.ack;
 
    if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
    {
      return ErrorCode::FAILED;
    }
 
    val = resp.rdata;
    return ErrorCode::OK;
  }

◆ 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.

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

◆ DpReadTxn()

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

inline

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

Parameters

reg	DP 读寄存器。DP read register.
val	输出：读到的数据。Output: read value.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 218 of file swd.hpp.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC = TransferWithRetry(SwdProtocol::make_dp_read_req(reg), resp);
    ack = resp.ack;
 
    if (EC != ErrorCode::OK)
    {
      return EC;
    }
 
    if (resp.ack != SwdProtocol::Ack::OK || !resp.parity_ok)
    {
      return ErrorCode::FAILED;
    }
 
    val = resp.rdata;
    return ErrorCode::OK;
  }

◆ DpWrite()

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

inline

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

Parameters

reg	DP 写寄存器。DP write register.
val	写入数据。Write value.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 197 of file swd.hpp.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC = Transfer(SwdProtocol::make_dp_write_req(reg, val), resp);
    if (EC != ErrorCode::OK)
    {
      ack = SwdProtocol::Ack::PROTOCOL;
      return EC;
    }
 
    ack = resp.ack;
    return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
  }

◆ DpWriteTxn()

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

inline

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

Parameters

reg	DP 写寄存器。DP write register.
val	写入数据。Write value.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 245 of file swd.hpp.

  {
    SwdProtocol::Response resp;
    const ErrorCode EC =
        TransferWithRetry(SwdProtocol::make_dp_write_req(reg, val), resp);
    ack = resp.ack;
 
    if (EC != ErrorCode::OK)
    {
      return EC;
    }
 
    return (resp.ack == SwdProtocol::Ack::OK) ? ErrorCode::OK : ErrorCode::FAILED;
  }

◆ 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 >.

◆ GetTransferPolicy()

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

inlinenodiscard

获取传输策略。Get transfer policy.

Definition at line 55 of file swd.hpp.

55{ return policy_; }

LibXR::Debug::Swd::policy_

TransferPolicy policy_

传输策略。Transfer policy.

Definition swd.hpp:474

◆ 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 >.

◆ InvalidateSelectCache()

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

inline

失效 SELECT 缓存。Invalidate SELECT cache.

Definition at line 422 of file swd.hpp.

  {
    select_valid_ = false;
    select_cache_ = 0u;
  }

◆ 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 >.

◆ 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.

  {
    return DpRead(SwdProtocol::DpReadReg::IDCODE, idcode, ack);
  }

◆ ResetResponse()

static void LibXR::Debug::Swd::ResetResponse ( SwdProtocol::Response & resp )

inlinestaticprivate

重置响应结构体为默认值。Reset response to defaults.

Parameters

resp	响应结构体。Response structure.

Definition at line 453 of file swd.hpp.

  {
    resp.ack = SwdProtocol::Ack::PROTOCOL;
    resp.rdata = 0u;
    resp.parity_ok = true;
  }

◆ 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 >.

◆ SetSelectCached()

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

inline

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

Parameters

select	SELECT 值。SELECT value.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 402 of file swd.hpp.

  {
    if (select_valid_ && (select_cache_ == select))
    {
      ack = SwdProtocol::Ack::OK;
      return ErrorCode::OK;
    }
 
    const ErrorCode EC = DpWriteTxn(SwdProtocol::DpWriteReg::SELECT, select, ack);
    if (EC == ErrorCode::OK && ack == SwdProtocol::Ack::OK)
    {
      select_cache_ = select;
      select_valid_ = true;
    }
    return EC;
  }

◆ 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 >.

◆ 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.

  {
    ResetResponse(resp);
 
    uint32_t retries = 0;
 
    while (true)
    {
      auto ec = Transfer(req, resp);
      if (ec != ErrorCode::OK)
      {
        resp.ack = SwdProtocol::Ack::PROTOCOL;
        InvalidateSelectCache();
        return ec;
      }
 
      // CMSIS-DAP IdleCycles：每次传输尝试后插入。CMSIS-DAP IdleCycles: insert after EACH
      // transfer attempt.
      if (policy_.idle_cycles != 0u)
      {
        IdleClocks(policy_.idle_cycles);
      }
 
      if (resp.ack != SwdProtocol::Ack::WAIT)
      {
        break;
      }
      if (retries >= policy_.wait_retry)
      {
        break;
      }
      ++retries;
    }
 
    if (resp.ack != SwdProtocol::Ack::OK)
    {
      InvalidateSelectCache();
    }
 
    if (resp.ack == SwdProtocol::Ack::FAULT && policy_.clear_sticky_on_fault)
    {
      (void)ClearStickyErrors();
    }
 
    return ErrorCode::OK;
  }

◆ WriteAbort()

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

inline

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

Parameters

flags	ABORT 标志位。ABORT flags.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 375 of file swd.hpp.

  {
    return DpWrite(SwdProtocol::DpWriteReg::ABORT, flags, ack);
  }

◆ WriteAbortTxn()

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

inline

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

Parameters

flags	ABORT 标志位。ABORT flags.
ack	输出：ACK。Output: ACK.

Returns: ErrorCode 操作结果。Error code.

Definition at line 386 of file swd.hpp.

  {
    return DpWriteTxn(SwdProtocol::DpWriteReg::ABORT, flags, ack);
  }

Field Documentation

◆ policy_

TransferPolicy LibXR::Debug::Swd::policy_ {}

private

传输策略。Transfer policy.

Definition at line 474 of file swd.hpp.

474{};

◆ select_cache_

uint32_t LibXR::Debug::Swd::select_cache_ = 0u

private

SELECT 缓存值。SELECT cached value.

Definition at line 476 of file swd.hpp.

◆ select_valid_

bool LibXR::Debug::Swd::select_valid_ = false

private

SELECT 缓存是否有效。SELECT cache valid.

Definition at line 477 of file swd.hpp.

The documentation for this class was generated from the following file:

src/driver/debug/swd.hpp

Data Structures

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ ApReadPostedTxn()

◆ ApReadTxn()

◆ ApWriteTxn()

◆ ClearStickyErrors()

◆ Close()

◆ DpRead()

◆ DpReadRdbuffTxn()

◆ DpReadTxn()

◆ DpWrite()

◆ DpWriteTxn()

◆ EnterSwd()

◆ GetTransferPolicy()

◆ IdleClocks()

◆ InvalidateSelectCache()

◆ LineReset()

◆ ReadIdCode()

◆ ResetResponse()

◆ SetClockHz()

◆ SetSelectCached()

◆ SetTransferPolicy()

◆ Transfer()

◆ TransferWithRetry()

◆ WriteAbort()

◆ WriteAbortTxn()

Field Documentation

◆ policy_

◆ select_cache_

◆ select_valid_