okHost is standard AXI, built to Arm’s AMBA AXI4 specification. These pages are a thin layer over it. They describe the interfaces at the bus level and cover only what is specific to okHost, meaning the signals it omits, the constants it drives, and its behaviors such as the operation timeout. For individual signal descriptions, the VALID/READY handshake, and timing (waveform) diagrams, see the Arm AMBA specifications.

okHost’s ports fall into two groups. One faces your design: the four AXI interfaces, the clock, the resets, and the board-ready and DNA outputs. The other is the host interface, through which all FrontPanel traffic flows.

okHost exposes only the AXI signals it uses. The omitted signals and driven constants are listed below. All four AXI interfaces are always present; there is no parameter to disable or remove one. Leave any port you do not use unconnected, and Vivado ties it off automatically.

A width shown as [*] varies by board or FPGA architecture; the .veo template for your board gives the exact range. See Instantiation Parameters.

okHost carries the standard AXI signal set for each protocol, minus the optional signals below, and drives fixed values on some of the sideband signals it keeps. The omissions and the driven constants define what your Subordinate must accommodate.

okHost omits the following optional signals, so you neither wire nor expect them:

• On AXI-Full and AXI-Lite: awid, arid, bid, and rid (no transaction-ID bus); awlock and arlock (no exclusive access); awqos and arqos; awregion and arregion; wstrb (no byte strobes); and all *user signals.
• On AXI-Stream: tkeep, tstrb, tid, tdest, and tuser on both directions, plus tlast on s_axis (FPGA to host) only.

Three consequences follow. Because there is no WSTRB, every AXI-Full and AXI-Lite write covers all bytes of every beat, so your Subordinate never sees a partial or byte-granular write. Because there are no TKEEP or TSTRB signals on AXI-Stream, every stream beat carries full-width data, with no null or position bytes. Because there is no ID bus, okHost issues a single implicit ID, so every transaction it issues completes in order.

On the sideband signals that are present, okHost drives fixed values that your Subordinate always sees.

A simple Subordinate may ignore AxCACHE and AxPROT, but must not gate access on the secure or privileged bits. Because AxPROT is fixed Non-secure and Unprivileged, a Subordinate that accepts only secure or only privileged accesses rejects every okHost access.

okHost reserves no address space of its own and exposes no hidden registers. AXI-Full and AXI-Lite are independent 64-bit address spaces; AXI-Stream has no address. The host API call selects the interface, and the address you pass is presented one-to-one to your Subordinate with no offset, so the memory map is yours to lay out.

okHost presents a single Manager per interface. To address several Subordinates, place an AXI interconnect between okHost and your endpoints; see Interface Routing on the System Design page.

Behavior unique to one interface appears under Per-Interface Specifics.

okHost is strictly host-initiated. Nothing moves on any AXI interface until the host issues an API call. okHost holds every channel idle until then, with VALID and READY deasserted, so your design responds to a transaction and never starts one.

Your FPGA design cannot autonomously push data or events to the host. There is no FPGA-to-host interrupt and no FPGA-initiated transaction on any interface.

A call stays active on the bus until it completes or its timeout expires. You can therefore issue a read or write before your design has the data ready, and okHost waits for it, holding VALID and READY asserted until the data moves. There is no need to confirm the data is ready first. Set the timeout to cover the expected wait. If you misjudge it and the data arrives late, the call returns a GatewareTimeout with the partial counts, so branch on that case in your host code. For a deterministic alternative, poll a data-available register you expose and issue the read only once it reports ready.

You may stall freely in either direction, and okHost holds the beat with nothing dropped, bounded only by the API call’s timeout. Backpressure is granular to the individual beat. Your logic can assert and deassert READY, or VALID on a read, on any cycle, and okHost matches it cycle by cycle. The beats of a transfer need not be contiguous, and a stall costs throughput but never data.

Every access okHost drives is aligned to the data-path width, which is stricter than the AXI specification requires. Your Subordinate therefore only ever sees width-aligned addresses and whole-width lengths, so lay out anything you place on the bus on width-aligned boundaries. On AXI-Full, both the address and the length are a multiple of the AXI-Full data-path width, which is set at build time. On AXI-Lite, the 32-bit path uses 4-byte-aligned addresses, and a bulk transfer moves whole 32-bit registers. On AXI-Stream, the length is a multiple of the stream data-path width; there is no address, so there is no address alignment. okHost enforces this by rejecting an unaligned address or a non-multiple length with UnsupportedFeature before any bus traffic. The data-path width depends on the bandwidth mode; see Bandwidth Modes on the USB Transport page.

Writes cap at 32 outstanding transactions. okHost presents a write address, streams that burst’s write data, and presents the next write address only once the current burst’s data has been fully accepted. It does not wait for the write response before moving on, so each burst whose BRESP has not yet returned holds one of the 32 slots. With a Subordinate that is slow to respond on the B channel, outstanding writes accumulate to the cap, at which point okHost throttles and waits for a BRESP to free a slot before issuing the next address. This rate-limits a large write behind a slow Subordinate, and one that never responds times the write out. Reads are not capped. An AXI-Lite bulk write is capped the same way, while a single AXI-Lite access is one transaction. Streams have no outstanding cap.

okHost maps its operations to a fixed set of error codes. The code meanings are documented on the Troubleshooting & Debugging page under Error Handling, and recovery under Recovery.

Every interface can return NoError, UnsupportedFeature (an unaligned address or a non-width-multiple length, reported before bus traffic), and GatewareTimeout, plus the global codes EntitlementFailed, FrontPanelNotEnabled, CommunicationError, and Failed. AXI-Full and AXI-Lite can also return AXISlaveError, which maps from your Subordinate’s SLVERR, and AXIDecodeError, which maps from a DECERR raised by the interconnect. AXI-Full can additionally return InvalidParameter for an out-of-range burst value, which must be 1 to 256 and is checked before bus traffic. AXI-Stream returns neither AXISlaveError nor AXIDecodeError, because it has no response channel and no address.

An AXI-Full read or write, or a bulk AXI-Lite run, moves many responses but returns one code. That code is the last non-OKAY response, held sticky. OKAY and EXOKAY never overwrite it, and each new non-OKAY response overwrites the previous one. Pair the code with the returned count to see how far the operation got. A single AXI-Lite access returns exactly that one transaction’s response. Streams have no sticky response, because they have no response channel.

Every data-moving operation returns a transfer byte count. An AXI-Full write and an AXI-Lite bulk write also return a transaction count. It is the number of write transactions your Subordinate completed on the B channel, one per burst on AXI-Full and one per register on an AXI-Lite bulk write. The AXI-Full burst count reflects the bursts okHost actually issued after 4 KB splitting, so it can exceed data_size divided by burst. A single AXI-Lite write or read returns only the error code, plus the value for a read. AXI-Stream returns a byte count only, with no transaction count. On a timeout, the counts reflect partial progress. Using the counts to diagnose a stalled channel is covered under Diagnosing with the Counts on the System Design page.

On a GatewareTimeout, the call returns the partial counts. A truncated read fills the undelivered bytes with 0xE7, and a truncated write drops the remainder. Because 0xE7 can collide with real data, trust the returned count, not the pattern. Re-issue the remainder or reset the interface.

okHost maps the bus to the host buffer least-significant-byte first. Each beat fills the next W bytes, where W is the data-path width, and buffer byte 0 holds the bus LSB. A wider or narrower bandwidth mode changes W but never the ordering. This mapping is the same for AXI-Full and AXI-Stream. AXI-Lite is the exception; see the AXI-Lite specifics below.

A single access is one single-beat transaction at one 4-byte-aligned address. A bulk access covers a run of consecutive, incrementing-address registers, which okHost decomposes into single-beat transactions in the gateware rather than in a host loop, so the run costs one host round trip. On the bus it is standard single-beat AXI-Lite with no bursts.

AXI-Lite is the exception to okHost’s byte order. It is register-granular rather than a byte buffer. A 32-bit register (reg [31:0]) in your gateware maps directly to the host’s 32-bit value, byte for byte, with no least-significant-byte-first assembly. AXI-Lite is always 32-bit regardless of bandwidth mode.

One API call is a single operation of data_size bytes (a 64-bit byte count) that okHost decomposes into bursts. The per-burst length is a value you provide. Read and Write take an optional burst argument of 1 to 256 beats, defaulting to 16. okHost issues bursts of that length back to back, truncating any burst that would cross a 4 KB address boundary and truncating the final burst to the remainder. One operation therefore becomes N bursts.

okHost does not key off RLAST to detect the end of a read. It counts read beats, totaled across the whole operation, to know when the read is done. Your Subordinate must therefore return exactly ARLEN + 1 beats per burst and the correct total across all bursts; under-delivering times the operation out. Still drive RLAST per the specification.

Length and end-of-data are set by the host API call. On m_axis_*, okHost asserts tlast on the last beat of the operation as the end-of-data marker for your sink, which must accept every beat of the operation. On s_axis_* there is no tlast; okHost ends the operation by counting bytes to the requested length, then deasserts tready.

okHost carries one stream per direction, with no TID or TDEST. To multiplex several logical streams, use an AXI4-Stream interconnect; see Interface Routing on the System Design page.

To instantiate okHost, copy its .veo template verbatim. The template lists every port and parameter, each with a comment, and is generated per board so the widths already match. The .veo and the other delivered files are covered on the Releases & Licenses page, and the full worked instantiation is covered under Integrating okHost on the System Design page.

Which parameters appear is board-dependent, because the .veo is generated per board.

The simulation use of SIM_BWMODE, including its per-mode data widths, is documented on the Simulation page.

okHost drives three outputs toward your design, not toward the host interface: board_ready, dna, and dna_valid. Leave any of them unconnected if you do not use it.

board_ready (1 bit) asserts when all physical PCB bring-up is complete and stays high thereafter. Hold your AXI-side logic in reset, or otherwise gate its start-up, until board_ready is high; the start-up sequence is under Integrating okHost on the System Design page.

dna ([95:0]) with dna_valid (1 bit) presents the FPGA’s Device DNA, its factory-programmed unique identifier (see AMD’s UG570, UltraScale Architecture Configuration User Guide). okHost exposes it because the DNA_PORTE2 primitive can be instantiated only once per device, and okHost already instantiates it. Read the value off this port rather than instantiating the primitive again, which would fail the build.

okHost provides three reset outputs, one per interface: axis_aresetn, axi_aresetn, and axil_aresetn. Each is active-low. Connect each to its interface’s logic. The host Reset API call pulses the corresponding aresetn, and the three are independent of each other.

okHost does not pulse the resets at power-on. To reset your interface logic at start-up, issue the interface reset yourself.

What a reset does. A reset resets nothing internally in okHost. It asserts that interface’s aresetn for 16 aclk cycles, then deasserts, where 16 cycles is AMD’s recommended width for resetting their AXI infrastructure IP. What that reset does downstream is determined by your modules and busing.

There is no whole-block okHost reset for you to drive; the three per-interface aresetn outputs are the only resets you get. okHost resets itself automatically when it needs to, inside FrontPanel’s proprietary firmware, and you never drive or observe it.

These resets are also the recovery mechanism; see Recovery on the Troubleshooting & Debugging page. Synchronizing a reset into a different clock domain, which is the common case, is a system-design topic; see Crossing Clock Domains on the System Design page.

okHost’s other edge, opposite your AXI design, is the host interface. It is the physical bus between okHost and the on-board transport device, through which all FrontPanel communication flows on hardware. okHost presents it as three signals, okUHU (inout), okUH (input), and okHU (output). Their widths vary by board and are shown here as [*].

You route them, but never use them. These signals are proprietary and are not a design interface. You do not drive, read, or build logic around them. Bring each net up to your top level, and okHost’s okHost.xdc constrains every one of them, setting pin LOC and IOSTANDARD, so you do not manage widths or pin assignment. In simulation the host interface plays no role; the BFM drives the AXI side directly, and the pins are width-1 stubs.

On the SZG-HUB1450-AU10P board, okUHU[4] and okUHU[5] need the board-specific PROCESSING_ORDER LATE setting; see Board-Specific Build Notes below.

Some boards need a project setting applied when you build, in your project-creation script, rather than an .xdc edit, because the setting configures the project or session rather than the design’s constraints. The per-board source of truth is the Notes header in that board’s delivered okHost.xdc and okHost.veo. Only boards that have notes appear here; a board with no notes needs nothing extra. The PerfTest project.tcl already applies these settings, so you need them when you build your own project; see Build the PerfTest Example on the Getting Started page.

Set okHost.xdc to evaluate late; this is required, or a DRC can fire.

set_property PROCESSING_ORDER LATE [get_files okHost.xdc]Code language: CSS (css)

The reason is that okUHU[4] and okUHU[5], the SYSMON I2C pins, share an I/O bank (VCCO equals SYZYGY VIO2) with SYZYGY Port C. okHost.xdc reads the Port C IOSTANDARD and matches okUHU[4] and okUHU[5] to it, so it must run after the design’s Port C constraints. See The Host Interface above.

Optionally suppress three known-harmless messages on Vivado 2025.2 and earlier. okHost’s IDELAYCTRL sets SIM_DEVICE = ULTRASCALE_PLUS, a value added in Vivado 2025.2.1. Earlier releases do not recognize it, so they drop it to the 7SERIES default, then change it to match the part, and raise DRC ADEF-911 for that change. SIM_DEVICE affects simulation only, and okHost is simulated with a separate FrontPanel model rather than this netlist, so the messages are harmless; okHost.xdc already waives the DRC so the bitstream completes. These set_msg_config calls only silence the messages, and they are inert on Vivado 2025.2.1 and later.

set_msg_config -suppress -id {Netlist 29-72}  -string {Incorrect value 'ULTRASCALE_PLUS' specified for property 'SIM_DEVICE'}
set_msg_config -suppress -id {Netlist 29-345} -string {of type 'IDELAYCTRL' is '7SERIES'; it is being changed to match the current FPGA architecture}
set_msg_config -suppress -id {DRC 23-412}     -string {ADEF-911}Code language: JavaScript (javascript)

• System Design: how to architect a system around okHost, covering interface routing, addressing, clocking and resets, CDC, FIFO sizing, structuring your core, and diagnosing with the counts.
• USB Transport: bandwidth modes, idle gaps, the reliability mechanism, and footprint.
• Getting Started: get okHost onto your board with the tutorial.
• Releases & Licenses: delivered files and Vivado version compatibility.
• Troubleshooting & Debugging: error-code meanings, debugging, and support.
• FrontPanel API: drive okHost from host software.
• Simulation: exercise okHost without hardware.