Mailbox Client IP の概要と使い方

1.　はじめに

Stratix^® 10 FPGA や Agilex™ FPGA には Secure Device Manager（以下、SDM）と呼ばれるハードコーデットされたモジュールがあります。
QSPI へのアクセスやリコンフィグレーション等を実施するには SDM を介して行われます。
そして、SDM へアクセスするにはマスターと SDM 間に Mailbox Client IP を含める必要があります。

Mailbox Client IP を介して SDM に処理させることのできる内容は下記の通りです。

Chip ID の取得
温度センサーの情報取得
電圧センサーの情報取得
QSPI に対するリード／ライトアクセス
Remote System Upgrade（RSU）

この記事では Mailbox Client IP の概要や使い方についてまとめています。
Mailbox Client IP を使用する際に必要な Command と Response の概念、ソフトで操作する際に便利な HAL API の紹介もございます。

この記事が設計の際にお役に立てれば幸いです。

2.　Mailbox Client IP 概要

2-1.　サポートデバイス

サポートデバイスは SDM が搭載されている下記デバイスとなります。

Stratix^® 10 FPGA
Agilex™ FPGA

2-2.　構成

Mailbox Client IP は【図 1】のような構成で使用されます。
Nios^® II や JTAG to Avalon Master などのマスターと SDM の間に Mailbox Client IP が存在します。

【図 1】Mailbox Client IP の構成図

3.　Command と Response

Mailbox Client IP には Command と Response の概念があります。
Command と Response の概念を予め知っておくことにより、動作をイメージして設計することができます。
また、Command と Response のやり取りについては、"5. HAL API" で紹介している HAL API を使用しますので、特に難しいプログラムコードは必要ありません。

3-1.　Master と SDM 間の全体像

Master と SDM 間は、Mailbox Client IP を介して Command／Response Packet でやり取りします（【図 2】参照）。
以下【図 2】の ① ～ ④ について補足します。

① Master と SDM 間は Mailbox Client IP を介して Command／Response Packet のやり取りをします。

② Command FIFO には Command Packet 送信のために必要な情報が格納されています。

③ Response FIFO には Response Packet 受信によって得られた情報が格納されています。

④ Master から Mailbox Client IP の Command／Response FIFO に対するアクセスです。
Command FIFO へはデータの入力、Response FIFO からはデータの取得を行います。

【図 2】Master-SDM 間のブロック図

3-2.　Command と Response のヘッダー

【図 2】の ① では Command／Response Packet のやり取りをしています。
この際、Packet の先頭には基本的な情報が記載されたヘッダーが送られます。ヘッダーのフォーマットは下図の通りです（【図 3】参照）。

そのため、ユーザーはこれらの情報を Master から Mailbox Client IP へ伝えなければなりません。

【図 3】Command ヘッダー
※ Mailbox Client IPs User Guide から抜粋

[31:28]　Reserved：予約済みビット
[27:24]　ID：任意の Command ID。Response ヘッダーは Command ヘッダーで指定した ID で返す。
[22:12]　Length： Command の引数の数（ヘッダーは除く）。
[10:0]　 Command／Error Code：送信時はコマンド、受信時は Error Code（success or fail）

3-3.　Command List and Description

ヘッダーに登録する Command や Length 等の情報はドキュメントの Command List に記載されています（【図 4】参照）。

【図 4】Command List
※ Mailbox Client IPs User Guide から抜粋

Command：コマンド
Code（Hex）：コマンドのコード
Command Length：引数の数（ヘッダーは除く）
Response Length：返答の数
Description：コマンド説明

3-4.　QSPI_READ の Command List の記載例

Command／Response ヘッダーに登録する情報は主に "3-3. Command List and Description" から取得することができます。
より、具体的に登録する情報をイメージできるよう、QSPI_READ コマンドを例に説明します。

QSPI_READ の Command List の記載の抜粋は【図 5】のようになっています。

【図 5】QSPI_READ の Command List
※ Mailbox Client IPs User Guide から抜粋

よって、QSPI_READ における Code、Command Length（引き数の数）、Response Length（返答の数）は下記となります。

【表 1】 QSPI_READ コマンドの構成

Code	3A → QSPI_READ のコマンドコード
Command Length	2 → Command Length の欄をご確認ください。具体的な引き数の内訳は表の説明欄をご確認ください。この場合は Read Address と Number of words to read の 2 つです。
Response Length	N → Command の第二引数で設定した Number of Words to read の値に依存します。

4.　IP パラメータ

Platform Designer における設定が必要な Mailbox Client IP の設定は下記の通りです。

Command Depth: Command FIFO の深さ（1 ～ 1024）
Response Depth: Response FIFO の深さ（1 ～ 1024）

Command／Response FIFO の深さは最大 1024 となります。
FIFO を深くすることによりロジックエレメント使用量が増加します。

【図 6】に Platform Designer の Mailbox Client IP 設定画面の例を示します。

【図 6】Platform Designer の Mailbox Client IP パラメーター

5.　HAL API

Mailbox Client IP では Nios^® II の HAL API が用意されています。
HAL API を使用することによって Mailbox Client IP を簡単に操作することができます。
HAL API は下記ファイルにて提供されています。

altera_s10_mailbox_client.h
altera_s10_mailbox_client.c
altera_s10_mailbox_client_flash.h
altera_s10_mailbox_client_flash.c

5-1.　HAL API を使用するための事前準備

HAL API を使用する際には事前に BSP-Editor で altera_safeclib を有効にしてください。
設定箇所は BSP-Editor の BSP Software Packages タブの altera_safeclib となります（【図 7】参照）。

【図 7】BSP-Editor での altera_safeclib 有効設定

5-2.　HAL API 一覧

Mailbox Client IP では下記の HAL API が用意されています。

【表 2】 Mailbox Client IP 関連 HAL API

HAL API	説明
mailbox_client_open()	Mailbox Client IP のサービスオープン
mailbox_client_send_cmd()	コマンドの実行
mailbox_client_flash_open()	QSPI オープン
mailbox_client_flash_close()	QSPI クローズ
mailbox_client_flash_get_info()	QSPI の情報取得
mailbox_client_flash_read()	QSPI リード
mailbox_client_flash_erase_block()	QSPI のセクターイレース
mailbox_client_flash_write_block()	QSPI セクターライト
mailbox_client_flash_write()	QSPI ライト

5-3.　QSPI_READ の操作例

QSPI_READ が実行できる HAL API は下記 2 種類があります。

mailbox_client_flash_read()
mailbox_client_send_cmd()

これらの HAL API を使用して QSPI_READ を行う方法について説明します。

5-3-1.　mailbox_client_flash_read()

この HAL API は QSPI_READ を行うために用意されています。
ドキュメントでの説明は【図 8】の通りです。

【図 8】mailbox_client_flash_read 概要
※ Mailbox Client IPs User Guide から抜粋

mailbox_client_flash_read() を使用する際の引数については、以下の内容を設定します。

【表 3】 mailbox_client_flash_read() の引数

引数	説明
fd	flash device structure のポインター。 ※ Mailbox_client_open() の戻り値を設定してください。
offset	QSPI のリードアドレス
dest_addr	QSPI からリードしたデータを格納する先のアドレス
length	リードする Length を設定（Byte 単位）

もし、QSPI の 0x00000004 番地から 4Byte をリードし、0x00000100 番地にリードデータを格納する際には、下記のような記述となります。

result = mailbox_client_flash_read(fd, 0x00000004, 0x00000100, 4);

※ 正常に動作した場合は戻り値が 0 となります。

5-3-2.　mailbox_client_send_cmd()

この HAL API は Mailbox Client IP に対し任意のコマンドを実行するために用意されています。
今回は例として QSPI_READ を実施する方法について説明します。
ドキュメントでの説明を【図 9】に示します。

【図 9】mailbox_client_send_cmd 概要
※ Mailbox Client IPs User Guide から抜粋

mailbox_client_send_cmd() を使用する際の引数については以下の内容を設定します。

【表 4】 mailbox_client_send_cmd() の引数

引数	説明
fd	flash device structure のポインター。 ※ Mailbox_client_open() の戻り値を設定してください。
id	他の実行コマンドと識別するための任意の ID。
cmd	Mailbox Client IP のコマンドコード。 QSPI_READ コマンドの場合は 3A。
arg	コマンドの引数を設定します。 QSPI_READ コマンドの場合は、引数としてリードアドレスとリードするデータ数を入力します。そのため arg ではこれら引数が格納されたアドレスを指定します。
arg_length	引数の数です。 QSPI_READ コマンドの場合は、リードアドレスとリードするデータ数なので、2 を設定します。
cmd_length	コマンドの長さ（arg_length + input data length）を指定します。
input_data	入力データ
resp_buf	レスポンスバッファ。 QSPI_READ コマンドの場合は、リードしたデータを格納するアドレスを指定します。
res_buf_len	レスポンスバッファの長さ（戻り値の数）。 QSPI_READ コマンドの場合は、リードしたデータの数が渡されます。

もし、Flash デバイスの 0x00000004 番地から 4Byte をリードし、0x00000100 番地にリードデータを格納する際には、下記のような記述となります。

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);

※ 正常に動作した場合は戻り値が 0 となります。

mailbox_client_send_cmd() は QSPI_READ 以外の他のコードでも使用可能です。

6.　参考

Mailbox Client IP の参考資料を下記紹介します。

■ ユーザーガイド

Mailbox Client IP のユーザーガイドは下記リンクをご参照ください。

参考：
Mailbox Client IPs User Guide

■ サンプル

tcl ベースで評価が可能なサンプルがメーカーから提供されています。
Stratix^® 10 FPGA と Agilex™ FPGA のそれぞれでサンプルが用意されておりますので、ご使用のデバイスに合わせてご参照ください。

参考： Agilex™ FPGA
Mailbox Client Intel FPGA IP Core Design Example（QSPI flash Access and Remote System Update）

参考： Stratix^®10 FPGA
Stratix 10 Mailbox Client Intel FPGA IP Core Design Example（QSPI flash Access and Remote System Update）

7.　おわりに

この記事では Mailbox Client IP の概要と Command／Response の概念、HAL API にフォーカスして説明しました。
Mailbox Client IP の機能や実装方法のイメージを掴んでいただく助けになれば幸いです。

今後、各処理が実装されたサンプルを提供予定ですので、実際動作させる際には本コンテンツでの情報を元にサンプルを活用いただければと思います。

1. はじめに

2. Mailbox Client IP 概要

2-1. サポートデバイス

2-2. 構成

3. Command と Response

3-1. Master と SDM 間の全体像

3-2. Command と Response のヘッダー

3-3. Command List and Description

3-4. QSPI_READ の Command List の記載例

4. IP パラメータ

5. HAL API

5-1. HAL API を使用するための事前準備

5-2. HAL API 一覧

5-3. QSPI_READ の操作例

5-3-1. mailbox_client_flash_read()

5-3-2. mailbox_client_send_cmd()

6. 参考

7. おわりに

関連記事