Mailbox Client Intel® FPGA IP User Guide

ID 683290
Date 4/10/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

1.10.2.5. Functions

Table 28.  librsu_init
Prototype: librsu_init(void)
Parameters: -
Return: Return 0 for success, or otherwise return error code 17
Description: Initialize the LibRSU HAL API
Table 29.  librsu_exit
Prototype: librsu_exit (void)
Parameters: -
Return: Return 0 for success, or otherwise return error code17
Description: Stop the LibRSU HAL API, and close the Mailbox Client Intel FPGA IP if opened.
Table 30.  rsu_slot_count
Prototype: rsu_slot_count (void)
Parameters: -
Return: Return 0 for success, or otherwise return error code17
Description: Get the number of defined slots.
Table 31.  rsu_slot_by_name
Prototype: rsu_slot_by_name (char *name)
Parameters:
  • name – name of slot
Return: Return 0 for success, or otherwise return error code17
Description: Get slot number based on name.
Table 32.  rsu_slot_get_info
Prototype: rsu_slot_get_info (int slot, struct rsu_slot_info *info)
Parameters:
  • slot – slot number
  • info – pointer to slot information structure
Return: Return 0 for success, or otherwise return error code17
Description: Get the attributes of a slot.
Table 33.  rsu_slot_size
Prototype: rsu_slot_size (int slot)
Parameters:
  • slot – slot number
Return: Return the size of the slot in bytes for success, or otherwise return error code17
Description: Get the size of a slot.
Table 34.  rsu_slot_priority
Prototype: rsu_slot_priority (int slot)
Parameters:
  • slot – slot number
Return: Return the priority of the slot for success, or otherwise return error code17
Description: Get the load priority of a slot. Priority of zero means the slot has no priority and is disabled. The slot with priority of one has the highest priority.
Table 35.  rsu_slot_erase
Prototype: rsu_slot_erase (int slot)
Parameters: slot – slot number
Return: Return 0 for success, or otherwise return error code17
Description: Erase all data in a slot to prepare for programming. Remove the slot if it is in the CPB.
Table 36.  rsu_slot_program_buf
Prototype: rsu_slot_program_buf (int slot, void *buf, int size)
Parameters:
  • slot– slot number
  • buf – pointer to data buffer
  • size – bytes to read from buffer
Return: Return 0 for success, or otherwise return error code17
Description: Program a slot using Intel FPGA bitstream data from a buffer and enter slot into CPB as highest priority. The slot must be erased first.
Table 37.  rsu_slot_program_callback
Prototype: rsu_slot_program_callback(int slot, rsu_data_callback callback)
Parameters:
  • slot – slot number
  • callback – callback function to provide input data
Return: Return 0 for success, or otherwise return error code17
Description: This function is to program and verify a slot using Intel FPGA config data provided by a callback function. Enter the slot (partition) into the CPB.
Table 38.  rsu_slot_program_verify_buf
Prototype: rsu_slot_verify_buf (int slot, void *buf, int size)
Parameters:
  • slot – slot number
  • buf – pointer to data buffer
  • size – bytes to read from buffer
Return: Return 0 for success, or otherwise return error code17
Description: Verify FPGA config data in a slot against a buffer.
Table 39.  rsu_slot_verify_callback
Prototype: rsu_slot_verify_callback(int slot, rsu_data_callback callback)
Parameters:
  • slot – slot number
  • callback – callback function to provide input data
Return: Return 0 for success, or otherwise return error code17
Description: Verify a slot using Intel FPGA bitstream provided by a callback function.
Table 40.  rsu_slot_copy_to_buf
Prototype: rsu_slot_copy_to_buf(int slot, alt_u64 address)
Parameters:
  • slot – slot number
  • address - address which stores the data in quad SPI.
Return: Return 0 for success, or otherwise return error code17
Description: Read the data in a slot and write to a buffer.
Table 41.  rsu_slot_enable
Prototype: rsu_slot_enable (int slot)
Parameters:
  • slot – slot number
Return: Return 0 for success, or otherwise return error code17
Description: Set the selected slot as the highest priority.
Table 42.  rsu_slot_disable
Prototype: rsu_slot_disable (int slot)
Parameters:
  • slot – slot number
Return: Return 0 for success, or otherwise return error code17
Description: Remove the selected slot from the priority scheme, but the slot data remains..
Table 43.  rsu_slot_load
Prototype: rsu_slot_load (int slot)
Parameters:
  • slot – slot number
Return: Return 0 for success, or otherwise return error code17
Description: Request the selected slot to be loaded immediately.
Table 44.  rsu_slot_load_factory
Prototype: rsu_slot_load_factory (void)
Parameters: -
Return: Return 0 for success, or otherwise return error code17
Description: Request the factory image to be loaded immediately.
Table 45.  rsu_slot_rename
Prototype: rsu_slot_rename (int slot, char *name)
Parameters:
  • slot – slot number
  • name – name of slot
Return: Return 0 for success, or otherwise return error code17
Description: Rename the selected slot.
Table 46.  rsu_slot_create
Prototype: rsu_slot_create (char *name, alt_u64 address, unsigned int size)
Parameters:
  • name – slot name
  • address – slot start address
  • size – slot size
Return: Return 0 for success, or otherwise return error code17
Description: Create a new slot to the SPT, using unused space.
Table 47.  rsu_slot_delete
Prototype: rsu_slot_delete (int slot)
Parameters:
  • slot – slot number
Return: Return 0 for success, or otherwise return error code17
Description: Delete the selected slot from SPT.
Table 48.  rsu_status_log
Prototype: rsu_status_log (struct rsu_status_info *info)
Parameters:
  • info – pointer to the rsu_status_info structure to fill in
Return: Return 0 for success, or otherwise return error code17
Description: Copy firmware status log into the rsu_status_info structure.
Table 49.  rsu_clear_error_status
Prototype: rsu_clear_error_status (void)
Parameters: -
Return: Return 0 for success, or otherwise return error code17
Description: Clear the error fields from the current status log.
Table 50.  rsu_dcmf_version
Prototype: rsu_dcmf_version (alt_u32 *version)
Parameters:
  • versions – pointer to where the four DCMF versions are stored
Return: Return 0 for success, or otherwise return error code17
Description: Retrieve the version of each of the four decision firmware copies in flash.
Table 51.  rsu_max_retry
Prototype: rsu_max_retry (alt_u8 *value)
Parameters:
  • value – pointer to where the max_retry is stored
Return: Return 0 for success, or otherwise return error code17
Description: Retrieve the max_retry parameter from flash.
Table 52.  rsu_dcmf_status
Prototype: rsu_dcmf_status (int *status)
Parameters:
  • status – pointer to where the status is stored
Return: Return 0 for success, or otherwise return error code17
Description: Determine whether decision firmware copies are corrupted in flash, with the currently used decision firmware being used as reference. The status is an array of four values, one for each decision firmware copy. A value of 0 means the copy is fine, anything else means the copy is corrupted.
Table 53.  rsu_create_empty_cpb
Prototype: rsu_create_empty_cpb (void)
Parameters: -
Return: Return 0 for success, or otherwise return error code17
Description: Create an empty CPB, which includes the CPB header only. All entries are marked as unused.
Table 54.  rsu_restore_cpb
Prototype: rsu_restore_cpb (alt_u64 address)
Parameters:
  • address – address of the buffer from which the CPB is restored
Return: Return 0 for success, or otherwise return error code17
Description: Restore CPB from a buffer in memory. The buffer must contain the 4096 bytes of CPB data, followed by 4 bytes containing the CRC32 checksum of the data.
Table 55.  rsu_save_cpb
Prototype: rsu_save_cpb (alt_u64 address)
Parameters:
  • address – address of the buffer where CPB is saved to
Return: Return 0 for success, or otherwise return error code17
Description: Save CPB to a memory buffer. A total of 4100 bytes are written: 4096 bytes for the data, plus 4 bytes with a CRC32 checksum of the data.
Table 56.  rsu_restore_spt
Prototype: rsu_restore_spt (alt_u64 address)
Parameters:
  • address – address of the buffer from which the SPT is restored
Return: Return 0 for success, or otherwise return error code17
Description: Restore SPT from a buffer in memory. The buffer must contain the 4096 bytes of SPT data, followed by 4 bytes containing the CRC32 checksum of the data.
Table 57.  rsu_save_spt
Prototype: rsu_save_spt (alt_u64 address)
Parameters:
  • address – address where SPT and CRC32 checksum are saved to
Return: Return 0 for success, or otherwise return error code17
Description: Save SPT to an address in memory. A total of 4100 bytes are written: 4096 bytes for the data, plus 4 bytes with a CRC32 checksum of the data.
Table 58.  rsu_running_factory
Prototype: rsu_running_factory (int *factory)
Parameters:
  • factory – value at this address is set to 1 if factory image is currently running, 0 otherwise
Return: Return 0 for success, or otherwise return error code17
Description: Determine if current running image is factory image.
17 Refer to Error Codes for more information.