Block

Blocks are the transaction units used by PyRogue for memory I/O.

At runtime, variables (especially pyrogue.RemoteVariable) are packed into one or more blocks. Read/write/verify operations are issued at block level, then values are mapped back to individual variables.

How Variables Use Blocks

For pyrogue.RemoteVariable:

• each variable defines offset/bit mapping metadata

• during device attach/build, device logic groups compatible remote variables into blocks

• each variable gets _block pointing to the block that services it

• transaction methods on Device/Root call block transactions, not per-variable raw bus operations

For pyrogue.LocalVariable:

• each variable uses a local software block (pyrogue.LocalBlock) for in-memory set/get behavior

Access Path (RemoteVariable)

Typical read/write path:

• user/API calls set or get on a variable

• Device/Root APIs enqueue block transactions

• block reads/writes memory through the device’s memory interface

• completion/check updates variable state and notifications

In bulk operations, many variables can share one block transaction, improving access efficiency versus isolated per-variable transfers.

Block Helper API

PyRogue provides helper functions around block transaction flow:

• pyrogue.startTransaction()

• pyrogue.checkTransaction()

• pyrogue.writeBlocks()

• pyrogue.verifyBlocks()

• pyrogue.readBlocks()

• pyrogue.checkBlocks()

• pyrogue.writeAndVerifyBlocks()

• pyrogue.readAndCheckBlocks()

These helpers are used by device-level methods and are the preferred extension points for custom block sequencing.

Implementation Boundary (Python and C++)

The block API you call from PyRogue maps to the rogue.interfaces.memory runtime layer.

In practice:

• Python code invokes methods on pyrogue.Device / pyrogue.RemoteVariable

• these route into block/variable objects exposed by rogue.interfaces.memory

• the underlying C++ block/variable code handles transaction staging, read/write/verify behavior, stale tracking, packing/unpacking, and update notification triggers

Hub interaction

Blocks are transaction sources; Hubs are transaction routers.

During a transaction, Hub logic:

• offsets addresses by local hub/device base

• forwards transaction to downstream memory slave

• splits transaction into sub-transactions when request size exceeds downstream max-access capability

This is why a variable-to-block transaction can still work cleanly across multi-level device trees with address translation.

For deeper internals and extension patterns, see:

• Blocks & Models

• Hub

• Memory Hub Example

• Memory Interface Class Descriptions

Example

# Bulk read all blocks attached to a device
myDevice.readBlocks(recurse=True)
myDevice.checkBlocks(recurse=True)

# Variable-specific transaction (targets variable._block)
myDevice.writeBlocks(variable=myDevice.MyReg, checkEach=True)

Block/LocalBlock Class Documentation

See LocalBlock for generated API details.