1.3.1. Operation Commands - 2026-01-30

The response includes a one-word argument for each bit set in the bitmask that are output in ascending channel order, corresponding to the order of the bits in the input mask (for example, if bits 0, 3, and 4 are set, the response words represent channels 0, 3, and 4, respectively). Each data word is encoded in unsigned U16.16 fixed-point format, with the upper 16 bits representing the integer portion in volts and the lower 16 bits the fractional portion.

For example, a voltage of 0.75V returns 0x0000C000. ³

Agilex™ 7 devices have a single voltage sensor. Consequently, the response is always one word.

The GET_TEMPERATURE command returns the temperature or temperatures of the core fabric or transceiver channel locations you specify.

The temperature returned is a signed fixed value with 8 bits below the binary point. For example, a temperature of 10°C returns 0x00000A00. A of temperature -1.5°C returns 0xFFFFFE80.

If the bitmask specifies an invalid Location, the command returns an error code which is any value in the range 0x80000000 -0x800000FF.

For Agilex™ 7 devices, refer to the Agilex™ 7 Power Management User Guide for more information about local build-in temperature sensors.

This command is for VID-enabled devices and allows read of 1 byte and 2 byte register contents of I2C devices over the PMBus. Specify the device address and register address to read, as command parameters.

The FPGA supports I2C device address in 7-bit format. Two groups of eight addresses (0000 XXX and 1111 XXX) are reserved and not accessible via Mailbox command.

The PMBus* Specification has definitions for registers in the address range of 0x00 - 0xAE. Register definitions beyond this range are defined by the I2C device’s manufacturer.

When successful, returns OK followed by the read data from the device. A failure response returns an error code.

Triggers reconfiguration from the data source that can be either the factory or an application image.

This command takes an optional 64-bit argument that specifies the reconfiguration data address in the flash. When sending the argument to the IP, you first send bits [31:0] followed by bits [63:32]. If you do not provide this argument its value is assumed to be 0.

• Bit [31:0]: The start address of an application image.
• Bit [63:32]: Reserved (write as 0).

Once the device processes this command, it returns the response header to response FIFO before it proceeds to reconfigure the device. Ensure the host PC or host controller stops servicing other interrupts and focuses on reading the response header data to indicate the command completed successfully. Otherwise, the host PC or host controller may not be able to receive the response once the reconfiguration process started.

Once the device proceeds with reconfiguration, the link between the external host and FPGA is lost. If you use PCIe in your design, you need to re-enumerate the PCIe link.

RSU_GET_SPT retrieves the quad SPI flash location for the two sub-partition tables that the RSU uses: SPT0 and SPT1.

The 4-word response contains the following information:

Reports the status of the last reconfiguration. You can use this command to check the configuration status during and after configuration. The response contains the following information:

Refer to Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions in the Mailbox Client IP User Guide for more information.

• Bit [31]: Current nSTATUS output value (active low)
• Bit [30]: Detected nCONFIG input value (active low)
• Bit [29:8]: Reserved
• Bit [7:6]: Configuration clock source
  • 01 = Internal oscillator
  • 10 = OSC_CLK_1
  • 11 = Secure PLL

• Bit [5]: Reserved
• Bit [4]: VID Enabled
• Bit [3]: Reserved
• Bit [2:0]: The MSEL value at power up

• Bit [31:6]: Reserved
• Bit [5]: HPS_WARMRESET
• Bit [4]: HPS_COLDRESET
• Bit [3]: SEU_ERROR
• Bit [2]: CVP_DONE
• Bit [1]: INIT_DONE
• Bit [0]: CONF_DONE

Flash offset of the highest priority failing application image. If multiple images are available in flash memory, stores the value of the first image that failed. A value of all 0s indicates no failing images. If there are no failing images, the remainder of the remaining words of the status information do not store valid information.

Returns 0 for no failures. Refer to Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions in the Mailbox Client IP User Guide for more information.

RSU interface version and error source.

For more information, refer to RSU Status and Error Codes section in the Hard Processor System Remote System Update User Guide.

Count of the number of retries that have been attempted for the current image. The counter is 0 initially. The counter is set to 1 after the first retry, then 2 after a second retry.

Specify the maximum number of retries in your Quartus^® Prime Settings File (.qsf). The command is: set_global_assignment -name RSU_MAX_RETRY_COUNT 3. Valid values for the MAX_RETRY counter are 1-3. The actual number of available retries is MAX_RETRY -1

This field was added in version 19.3 of the Quartus^® Prime Pro Edition software.

This command is not available before version 19.3 of the Quartus^® Prime Pro Edition software.

Requests exclusive access to the quad SPI. You issue this request before any other QSPI requests. The SDM accepts the request if the quad SPI is not in use and the SDM is not configuring the device. Returns OK if the SDM grants access. Upon receiving the OK response, issue the QSPI_SET_CS command to select the flash devices.

The SDM grants exclusive access to the client using this mailbox. Other clients cannot access the quad SPI until the active client relinquishes access using the QSPI_CLOSE command.

Access to the QSPI flash memory devices using SDM_IO pins is only available for the AS x4 configuration scheme, JTAG configuration, and a design compiled for AS x4 configuration. For the Avalon^® streaming interface ( Avalon^® ST) configuration scheme, you must connect QSPI flash memories to GPIO pins.

Access to the quad SPI flash memory devices via any mailbox client IP is not available by default in designs that include the HPS, unless you disable the QSPI in HPS software configuration.

• Bits[31:28]: Flash device to select. Refer to information below for the value that corresponds to the nCSO[0:3] pins.
  • Value 4'h0000 selects the flash that corresponds to nCSO[0].
  • Value 4'h0001 selects the flash that corresponds to nCSO[1].
  • Value 4'h0002 selects the flash that corresponds to nCSO[2].
  • Value 4'h0003 selects the flash that corresponds to nCSO[3].
• Bits[27:0]: Reserved (write as 0).

During AS x4 configuration scheme in Stratix^® 10 devices, this command is optional. The chip select line follows the last executed QSPI_SET_CS command or defaults to nCSO[0] after the AS x4 configuration.

During AS x4 configuration scheme in Agilex™ 7 devices, this command is required after every QSPI_OPEN command.

During JTAG configuration scheme, this command is required after every QSPI_OPEN command.

Reads the attached quad SPI device. The maximum transfer size is 4 kilobytes (KB) or 1024 words.

For a partially successful read, QSPI_READ may erroneously return the OK status.

Writes data to the quad SPI device. The maximum transfer size is 4 kilobytes (KB) or 1024 words.

To prepare memory for writes, use the QSPI_ERASE command before issuing this command.

• The flash address offset to start the erase (one word). Depending on the number of words to erase, the start address must be:
  • 4 KB aligned if number words to erase is 0x400
  • 32 KB aligned if number words to erase is 0x2000
  • 64 KB aligned if number words to erase is 0x4000
  Returns an error for non-4/32/64 KB aligned addresses.
• The number of words to erase is specified in multiples of:
  • 0x400 to erase 4 KB (1024 words) of data. This option is the minimum erase size.
  • 0x2000 to erase 32 KB (8192 words) of data
  • 0x4000 to erase 64 KB (16384 words) of data

• The opcode for the read command.
• The number of bytes to read.

A successful read returns the OK response code followed by the data read from the device. The read data return is in multiple of 4 bytes. If the bytes to read is not an exact multiple of 4 bytes, it is padded with multiple of 4 bytes until the next word boundary and the padded bit value is zero.

• The opcode for the write command.
• The number of bytes to write.
• The data to write.

To perform a sector erase or sub-sector erase, you must specify the serial flash address in most significant byte (MSB) to least significant byte (LSB) order as the following example illustrates.

To erase a sector of a Micron 2 gigabit (Gb) flash at address 0x04FF0000 using the QSPI_WRITE_DEVICE_REG command, write the flash address in MSB to LSB order as shown here:

Header: 0x00003036

Opcode: 0x000000DC

Number of bytes to write: 0x00000004

Flash address: 0x0000FF04

A successful write returns the OK response code. This command pads data that is not a multiple of 4 bytes to the next word boundary. The command pads the data with zero.

• The opcode to send the quad SPI device.

A successful command returns the OK response code.

This command takes two 32-bit words as arguments.

Word 0:

• Bits [1:0]: SHA Variant. This parameter determines the type of SHA algorithm used. It can take the following values:
  • 00: SHA512
  • 01: SHA384
  • 10: SHA256
• Bits[31:2]: Start Address. This is the address in flash to start verifying from. The address must be 4 bytes aligned.

Word 1:

• Bits [31:0]: NumBytes. This represents the number of bytes to be used in the SHA read. Must be a multiple of 64.

Typically, configuration cycle count is captured in the lower 32 bits. It is unlikely that the firmware returns a 64-bit cycle count. If this happens, you must concatenate the two 32-bit words to obtain the total cycle count value.

Example:

Returned response: 0x007C27EE = 8136686 cycles

Configuration control clock frequency: 200 MHz

Configuration time: (8136686/200000000) × 1000 = 40.68 ms

• 1 if Error Message Queue is empty; else
• Length +2, up to FIFO size[17]

When an SEU error is detected, the error information is stored in the error message queue. This command provides a way to inspect the queue and remove entries from it.

When you set the SEU_ERROR pin in the Device and Pin Options window, you may observe that the SEU_ERROR signal remains high when there is one or more errors in the error message queue. The signal goes low when the error message queue is empty.

The response is one word long when there are no errors in the error message queue.

When there is one or more errors in the queue, the first error from the queue is removed and returned in the subsequent words. This command returns one element from the queue at a time.

Provides an interface for Power Management Firmware (PMF) and Voltage Regulator (VR) data. This command is for VID-enabled devices with both VR polling and PMF also enabled.

This command is available in the Quartus^® Prime Pro Edition software version 23.3 or later.