1. Introduction
Stratix® 10 FPGAs and Agilex™ FPGAs have a hard-coded module called the Secure Device Manager (SDM).
Access to QSPI, reconfiguration, and other operations are performed through the SDM.
To access the SDM, the master and the SDM must communicate with each other via the Mailbox Client IP must be included between the master and SDM to access SDM.
The following is a list of what can be processed by SDM via the Mailbox Client IP The SDM can process the following via the Mailbox Client IP.
Acquisition of Chip ID
Obtaining temperature sensor information
Acquisition of voltage sensor information
Read/write access to QSPI
Remote System Upgrade (RSU)
This article provides an overview of the Mailbox Client IP and its usage.
It also introduces the concepts of Command and Response, which are necessary when using the Mailbox Client IP, and the HAL API, which is useful when using the software.
We hope this article will be useful for your design. 2.
2. Overview of Mailbox Client IP
2-1. Support Devices
Supported devices are the following devices equipped with SDM.
Stratix® 10 FPGA
Agilex™ FPGA
2-2. configuration
The Mailbox Client IP is used in the configuration shown in [Figure 1].
Nios® II, JTAG to Avalon Master, etc. The Mailbox Client IP exists between the master and the SDM.
Figure 1 Mailbox Client IP Configuration
3. Command and Response
The Mailbox Client IP has the concept of Command and Response.
By knowing the concept of Command and Response in advance, you can design the IP with an image of its operation.
Also, since the HAL API introduced in "5. HAL API " is used to exchange Command and Response, no complicated program code is required. 3-1.
3-1. Overview between Master and SDM
Command/Response Packets are exchanged between the Master and SDM via the Mailbox Client IP (see Figure 2).
The following is a supplemental explanation of (1) through (4) in Figure 2.
(1) Command/Response Packets are exchanged between the master and SDM via the Mailbox Client IP.
(2) The Command FIFO contains information necessary for sending Command Packets.
(3) Response FIFO stores the information obtained by receiving Response Packets.
(4) The Command FIFO is used to input data to Command FIFO and the Response FIFO is used to retrieve data.
Figure 2 Block Diagram between Master and SDM
3-2. Command and Response Headers
In Figure 2 (1), Command and Response Packets are exchanged.
In this case, a header containing basic information is sent at the beginning of the Packet. The format of the header is shown in the figure below (see Figure 3).
Therefore, the user must convey this information from the Master to the Mailbox Client IP.
Figure 3 Command Header
* Excerpt from the Mailbox Client IPs User Guide
- [31:28] Reserved: Reserved bits
- [27:24] The Response header returns with the ID specified in the Command header.
- [22:12] Length: Number of arguments to Command (excluding headers).
- [10:9] Command/Error Code: Command for sending, Error Code for receiving. (success or fail)
3-3. Command List and Description
Information such as Command and Length to be registered in the header is described in the Command List of the document (see Figure 4).
Figure 4 Command List
* Excerpt from Mailbox Client IPs User Guide
Command: Command
Code (Hex): Command code
Command Length: Number of arguments (excluding headers)
Response Length： Number of responses
Description： Command description
3-4. Example of QSPI_READ Command List
The information to be registered in the Command/Response header can be mainly obtained from "3-3.
The QSPI_READ command is used as an example to give a more concrete image of the information to be registered.
Figure 5 shows an excerpt from the QSPI_READ Command List.
Figure 5 Command List of QSPI_READ
* Excerpt from Mailbox Client IPs User Guide
The following table shows the Code, Command Length (number of pulls), and Response Length (number of replies) in QSPI_READ.
Table 1 Composition of the QSPI_READ Command
| Code |
3A → Command code for QSPI_READ |
| Command Length |
2 → Check the Command Length column. For a specific breakdown of the number of words to be read, see the explanation column of the table. In this case, it is Read Address and Number of words to read. |
| Response Length |
N → Depends on the value of Number of Words to read set in the second argument of Command. 4. |
4. IP Parameters
The Mailbox Client IP settings that need to be configured in Platform Designer are as follows.
Command Depth: Depth of Command FIFO (1 to 1024)
Response Depth: Depth of Response FIFO (1 to 1024)
The maximum Command/Response FIFO depth is 1024.
Increasing the FIFO depth increases logic element usage.
Figure 6 shows an example of the Mailbox Client IP setting screen in Platform Designer.
Figure 6 Mailbox Client IP Parameters in Platform Designer
5. HAL API
The Mailbox Client IP provides the Nios® II HAL API.
By using the HAL API, Mailbox Client IP can be easily operated.
The HAL API is provided in the following file.
altera_s10_mailbox_client.h
altera_s10_mailbox_client.c
altera_s10_mailbox_client_flash.h
altera_s10_mailbox_client_flash.c
5-1. Preparation for using HAL API
Before using HAL API, please enable altera_safeclib in BSP-Editor.
The setting point is altera_safeclib in the BSP Software Packages tab of BSP-Editor (see Figure 7).
Figure 7 Enabling altera_safeclib in BSP-Editor
5-2. HAL API List
Mailbox Client IP provides the following HAL APIs.
Table 2 HAL APIs related to Mailbox Client IP
| HAL API | HAL API Description |
| mailbox_client_open() | Opens the Mailbox Client IP service. |
| mailbox_client_send_cmd() | Execute a command |
| mailbox_client_flash_open() | Opens QSPI |
| mailbox_client_flash_close() | QSPI close |
| mailbox_client_flash_get_info() | Get QSPI information |
| mailbox_client_flash_read() | QSPI read |
| mailbox_client_flash_erase_block() | QSPI sector erase |
| mailbox_client_flash_write_block() | QSPI sector write |
| mailbox_client_flash_write() | QSPI write |
5-3. example of QSPI_READ operation
There are the following two types of HAL APIs that QSPI_READ can execute.
- mailbox_client_flash_read()
- mailbox_client_send_cmd()
This section describes how to perform QSPI_READ using these HAL APIs.
5-3-1. mailbox_client_flash_read()
This HAL API is provided to perform QSPI_READ.
The description in the document is as shown in Figure 8.
Figure 8 mailbox_client_flash_read Overview
* Excerpt from Mailbox Client IPs User Guide
The following arguments are set when using mailbox_client_flash_read().
Table 3 Arguments of mailbox_client_flash_read()
| Argument | Description |
| fd | Pointer to flash device structure Set the return value of Mailbox_client_open(). |
| offset | QSPI read address |
| dest_addr | Destination address to store data read from QSPI |
| length | Set the length to read (in bytes). |
If 4 bytes are read from QSPI address 0x00000004 and the read data is stored at address 0x00000100, the following statement is used.
result = mailbox_client_flash_read(fd, 0x00000004, 0x00000100, 4);The return value is 0 in case of normal operation. 5-3-2.
5-3-2. mailbox_client_send_cmd()
This HAL API is provided to execute arbitrary commands to the Mailbox Client IP.
This time, we will explain how to execute QSPI_READ as an example.
Figure 9 shows the description in the document.
Figure 9 mailbox_client_send_cmd Overview
* Excerpt from Mailbox Client IPs User Guide
The following arguments are set when using mailbox_client_send_cmd().
Table 4 Arguments of mailbox_client_send_cmd()
| Argument | Description |
| fd | Pointer to flash device structure Set the return value of Mailbox_client_open(). |
| id | Arbitrary ID to distinguish from other execution commands. |
| cmd | Command code of Mailbox Client IP. 3A in case of QSPI_READ command. |
| arg | Sets the arguments of the command. For the QSPI_READ command, the read address and the number of data to be read are entered as arguments. Therefore, arg specifies the address where these arguments are stored. |
| arg_length | The number of arguments. In the case of the QSPI_READ command, this is the read address and the number of data to be read, so set this to 2. |
| cmd_length | Specifies the length of the command (arg_length + input data length). |
| input_data | Input data |
| resp_buf | Response buffer. For the QSPI_READ command, specifies the address where the read data is stored. |
| res_buf_len | Length of response buffer (number of return values). For the QSPI_READ command, the number of data read is passed. |
If 4Byte is read from the Flash device at 0x00000004 and the read data is stored at 0x00000100, the description would be as follows
arg[0] = 0x00000004; // QSPI read address
arg[1] = 4; // read bytes
result = mailbox_client_send_cmd(fd, id, 3A, arg, 2, 2, 1, 0, resp_buf, 1);The return value is 0 in case of normal operation.
mailbox_client_send_cmd() can be used with other codes except QSPI_READ.
6. reference
The following are reference materials for Mailbox Client IP.
User Guide
Please refer to the following link for the user guide of Mailbox Client IP.
Reference:
Mailbox Client IPs User Guide
Samples
Samples that can be evaluated based on tcl are available from the manufacturer.
Samples are available for both Stratix® 10 FPGA and Agilex™ FPGA, so please refer to them according to your device.
Reference: Agilex™ FPGA
Mailbox Client Intel FPGA IP Core Design Example (QSPI flash Access and Remote System Update)
Reference: Stratix® 10 FPGA
Stratix 10 Mailbox Client Intel FPGA IP Core Design Example (QSPI flash Access and Remote System Update)
7. Conclusion
In this article, we focused on the overview of Mailbox Client IP, Command/Response concepts, and HAL API.
We hope that this article will help you grasp an image of the Mailbox Client IP functions and implementation.
We are planning to provide samples that implement each process in the future, so we hope that you will make use of the samples based on the information in this content when actually running them.