Mailbox Client Intel® FPGA IPs User Guide

Download PDF
ID 683290
Date 11/04/2024
Public
Document Table of Contents
Document Table of Contents x
1. Mailbox Client Intel FPGA IP User Guide 2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions
1. Mailbox Client Intel FPGA IP User Guide x
1.1. Release Information 1.2. Device Family Support 1.3. Parameters 1.4. Mailbox Client Intel® FPGA IP Core Interface Signals 1.5. Mailbox Client Intel FPGA IP Avalon® Memory-Mapped Interface 1.6. Commands and Responses 1.7. Specifying the Command and Response FIFO Depths 1.8. Enabling Cryptographic Services 1.9. Using the Mailbox Client Intel® FPGA IP 1.10. Accessing Quad SPI Flash Mailbox Client Intel FPGA IP Core Use Case Examples 1.11. Nios® II and Nios® V Processors HAL Driver 1.12. Mailbox Client Intel FPGA IP User Guide Archives 1.13. Document Revision History for the Mailbox Client Intel® FPGA IP User Guide
1.4. Mailbox Client Intel® FPGA IP Core Interface Signals x
1.4.1. Clock and Reset Interfaces 1.4.2. Avalon® Memory-Mapped Interface 1.4.3. AXI Manager Interface
1.5. Mailbox Client Intel FPGA IP Avalon® Memory-Mapped Interface x
1.5.1. Interrupt Enable Register 1.5.2. Interrupt Status Register 1.5.3. Timer Registers
1.6. Commands and Responses x
1.6.1. Operation Commands 1.6.2. Error Code Responses 1.6.3. Error Code Recovery
1.11. Nios® II and Nios® V Processors HAL Driver x
1.11.1. Mailbox Client HAL API 1.11.2. LibRSU HAL API
1.11.1. Mailbox Client HAL API x
1.11.1.1. Mailbox Client Driver API
1.11.2. LibRSU HAL API x
1.11.2.1. Configuration Parameter 1.11.2.2. Error Codes 1.11.2.3. Using LibRSU HAL API without Valid SPT or CPB 1.11.2.4. Data Type 1.11.2.5. Functions 1.11.2.6. RSU Client API
1. Mailbox Client Intel FPGA IP User Guide
2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions

1.11.1.1. Mailbox Client Driver API

Table 16.  mailbox_client_open
Prototype: mailbox_client_open(const char *name)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client.h>
For Agilex™ 5 devices <intel_mailbox_client.h>
Parameter:
  • name – character pointer to name of Mailbox Client Intel® FPGA IP peripheral as registered with the HAL
Return: Return non-NULL if successful and otherwise return:
  • -NULL for invalid argument. Found no device or wrong input name
Description: Retrieve a pointer to the Mailbox Client block instance. Search for the list of registered mailbox client instances for the one with the supplied name.
Table 17.  mailbox_client_send_cmd
Prototype: mailbox_client_send_cmd (intel_mailbox_client* fd, alt_u8 id, alt_u32 cmd, alt_u32* arg, int arg_length, int cmd_length, alt_u32* input_data, alt_u32* resp_buf, alt_u32 resp_buf_len) 17
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client.h>
For Agilex™ 5 devices <intel_mailbox_client.h>
Parameter:
  • fd – pointer to the flash device structure
  • id - command ID
  • cmd - mailbox client command
  • arg - mailbox client argument 18
  • arg_length - number of arguments
  • cmd_length - command length (arg_length + input_data length)
  • input_data - input data
  • resp_buf - response buffer
  • res_buf_len - response buffer length
Return: Return 0 if successful and otherwise return:
  • error codes for mailbox client in Error Code Responses
  • -EINVAL for Invalid argument
  • -ETIME for polling timeout and skipping the loop after 5 seconds
  • -EBACK_TOUT for back pressure timer interrupt 19
  • -EEOP_TOUT for end of packet timer interrupt 20
  • -ECMD_INVLD for invalid command interrupt
  • -ENOBUFS for the response buffer length is insufficient 21
  • -ENOSYS for unmatched returned command ID from SDM
Description: Send commands and data to the mailbox client. Reads back the response when data valid interrupt occurs.
Table 18.  mailbox_client_flash_open
Prototype: mailbox_client_flash_open(intel_mailbox_client* fd)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
  • -ENODEV for unrecognized flash device
Description: Send command to the mailbox client for QSPI open and QSPI chip select. Provides exclusive access to the quad SPI interface. Determines the QSPI flash size.
Table 19.  mailbox_client_flash_close
Prototype: mailbox_client_flash_close(intel_mailbox_client* fd)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
Description: Send command to the mailbox client for QSPI close. Stops the exclusive access to the quad SPI interface.
Table 20.  mailbox_client_flash_get_info
Prototype: mailbox_client_flash_get_info(intel_mailbox_client* fd, flash_region** info, int* number_of_regions)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • info - pointer to the flash region
  • number_of_regions - pointer to the number of regions
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
  • -EIO for possible hardware issue
Description: Provide information corresponding to nCSO[0].

Returns the flash memory offset, flash memory size, number of flash device, number of sector, and sector size values.
Table 21.  mailbox_client_flash_read
Prototype: mailbox_client_flash_read (intel_mailbox_client* fd, int offset, void* dest_addr, int length)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • offset - read flash address (unaligned access)
  • dest_addr - destination buffer (in byte size)
  • length - size of read data (in byte size)
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
Description: Read data from selected address specified by the length in byte size. Length is a non-zero value.
Table 22.  mailbox_client_flash_erase_block
Prototype: mailbox_client_flash_erase_block (intel_mailbox_client* fd, int block_offset)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • block_offset - address offset from the start of flash sector specified to be erased
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
  • -EIO for erase failed and sector might be protected
Description: Erase a single flash sector.
Table 23.  mailbox_client_flash_write_block
Prototype: mailbox_client_flash_write_block (intel_mailbox_client* fd, int block_offset, int data_offset, const void* data, int length)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • block_offset - sector address. Starts at the flash sector specified to be written to
  • data_offset - byte offset (unaligned access) of write into memory
  • data - data buffer to be written (in byte size)
  • length - size of write data (in byte size)
Return: Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
Description: Write one block or sector of data into the flash. The write data length cannot split between adjacent sectors.

The function assumes the address is empty. You must erase it prior its programming.
Table 24.  mailbox_client_flash_write
Prototype: mailbox_client_flash_write (intel_mailbox_client* fd, int offset, const void* src_addr, int length)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • offset - flash address (unaligned access) of write to the flash memory
  • src_addr - source buffer (in byte size)
  • length - size of write data (in byte size)
Return:
Return 0 if successful and otherwise return:
  • -EINVAL for invalid argument
Description: Program the data into the flash at the selected address. Automatically erase the block as needed before programming.
Table 25.  mailbox_client_flash _erase_block
Prototype: mailbox_client_flash_erase_block(intel_mailbox_client* fd, int block_offset, int block_size)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • block_offset – address offset from the start of flash sector specified to be erased
  • block_size – sector of the quad SPI device. Input the following value:
    • 4096 for 4 KB sector size
    • 32768 for 32 KB sector size
    • 65536 for 64 KB sector size
Return:
Return 0 for success and otherwise return:
  • EINVAL for invalid argument
Description: Erase a single flash sector depends on block size given.
Table 26.  mailbox_client_flash _erase
Prototype: mailbox_client_flash_erase(intel_mailbox_client* fd, int offset, int length)
Include: For
  • Stratix® 10 devices
  • Agilex™ 7 devices
<altera_s10_mailbox_client_flash.h>
For Agilex™ 5 devices <intel_mailbox_client_flash.h>
Parameter:
  • fd – pointer to the flash device structure
  • offset – address offset from the start of flash sector specified to be erased
  • length – size of erase data in the multiple of 4096 bytes
Return:
Return 0 for success and otherwise return:
  • EINVAL for invalid argument
Description: Erase the flash according to the length given
Related Information
17 Prior to Quartus® Prime Pro Edition software version 21.3, the response buffer length (resp_buf_len) was declared as a pointer rather than an integer.
18 Argument represents the parameters needed for mailbox client operation, not including input data.
19 The recommended error code recovery is the full system reconfiguration.
20 The recommended error code recovery is to reset the Mailbox Client Intel® FPGA IP.
21 If the response buffer length is insufficient, the HAL API discards the collected data from Mailbox Client Intel® FPGA IP and return ENOBUFS.
Level Two Title