JtagDriver

JtagDriver objects in C++ are referenced by the following shared pointer typedef:

typedef std::shared_ptr<rogue::protocols::xilinx::JtagDriver> rogue::protocols::xilinx::JtagDriverPtr

The class description is shown below:

class JtagDriver

Base transport driver for the AxisToJtag firmware protocol.

JtagDriver implements protocol framing, query/shift command handling, retry logic, and vector chunking for XVC/JTAG operations. Concrete transport drivers derive from this class and provide I/O primitives.

Transport subclasses must implement:

  • xfer() to move opaque protocol messages to/from the target.

  • getMaxVectorSize() to report maximum JTAG vector bytes supported by the transport.

Message sizing:

  • Transport receives at most 2 * getMaxVectorSize() + getWordSize() bytes in one transfer request.

  • Protocol messages may contain two vectors plus protocol header.

xfer() contract:

  • transmit txBytes from txb.

  • receive exactly hsize header bytes into hdbuf (or throw on short read).

  • receive up to size payload bytes into rxb.

  • return number of payload bytes written to rxb.

  • throw on timeout/error so retry/error handling can be applied by xferRel().

Subclassed by rogue::protocols::xilinx::Xvc

Public Functions

explicit JtagDriver(uint16_t port)

Constructs the JTAG driver base state.

This constructor is a low-level C++ allocation path. Prefer create() when shared ownership or Python exposure is required.

Parameters:

port – Transport/service port value associated with this driver.

virtual void init()

Performs post-construction initialization.

Base implementation performs target query to cache protocol parameters.

inline virtual int xfer(uint8_t *txb, unsigned txBytes, uint8_t *hdbuf, unsigned hsize, uint8_t *rxb, unsigned size)

Transport-level transfer primitive implemented by subclass.

Sends request bytes and receives reply header/payload for one protocol transaction.

Parameters:

  • txb – Request transmit buffer.

  • txBytes – Number of transmit bytes in txb.

  • hdbuf – Reply header destination buffer.

  • hsize – Number of reply header bytes expected.

  • rxb – Reply payload destination buffer.

  • size – Maximum payload bytes to store in rxb.

Throws:

rogue::GeneralError – On transport/protocol timeout or I/O error.

Returns:

Number of payload bytes received.

virtual int xferRel(uint8_t *txb, unsigned txBytes, Header *phdr, uint8_t *rxb, unsigned sizeBytes)

Executes transfer with retry and protocol validation.

Calls xfer() repeatedly up to retry limit, checks header/error fields, validates transaction ID where applicable, and returns payload length.

Parameters:

  • txb – Request transmit buffer.

  • txBytes – Number of transmit bytes in txb.

  • phdr – Optional destination for parsed reply header.

  • rxb – Reply payload destination buffer.

  • sizeBytes – Maximum payload bytes accepted in rxb.

Throws:

rogue::GeneralError – If retries are exhausted or protocol errors persist.

Returns:

Number of payload bytes received.

virtual uint64_t query()

Queries target capabilities and caches protocol parameters.

Updates cached word size, memory depth, and period information. If target reports no memory (0), streaming semantics apply.

Returns:

Maximum target-supported vector size in bytes (or 0 for streaming target).

inline virtual uint64_t getMaxVectorSize()

Returns transport-supported maximum vector size in bytes.

This value is transport-specific and may differ from target capability. Effective runtime vector length is bounded by the minimum of transport and target limits.

Returns:

Maximum transport-supported vector size in bytes.

virtual uint32_t setPeriodNs(uint32_t newPeriod)

Requests update of TCK period.

Base behavior returns current period when newPeriod == 0; otherwise returns requested period if target period is unknown, or current cached period when fixed by target.

Parameters:

newPeriod – Requested period in nanoseconds.

Returns:

Effective period in nanoseconds.

virtual void sendVectors(uint64_t numBits, uint8_t *tms, uint8_t *tdi, uint8_t *tdo)

Sends JTAG TMS/TDI vectors and receives TDO.

Vectors are interpreted little-endian (first transmitted/received bits at lowest byte offsets). Large vectors are chunked according to target and transport capabilities.

Parameters:

  • numBits – Number of bits in each input vector.

  • tms – Pointer to TMS vector bytes.

  • tdi – Pointer to TDI vector bytes.

  • tdo – Pointer to output TDO vector bytes.

virtual void dumpInfo(FILE *f = stdout)

Dumps cached driver/target information.

Parameters:

f – Output stream (stdout by default).

inline bool isDone()

Returns completion/shutdown flag.

Returns:

true when driver is marked done; otherwise false.

Public Static Functions

static std::shared_ptr<rogue::protocols::xilinx::JtagDriver> create(uint16_t port)

Creates a JTAG driver instance.

Parameter semantics are identical to the constructor; see JtagDriver() for driver-construction details. This static factory is the preferred construction path when the object is shared across Rogue graph connections or exposed to Python. It returns std::shared_ptr ownership compatible with Rogue pointer typedefs.

Parameters:

port – Transport/service port value associated with this driver.

Returns:

Shared pointer to the created driver.

static void setup_python()

Registers Python bindings for this class.