libspe2
出典: CellFanWiki
libspe は、SPEを実行／管理／利用するためのライブラリであり、ドキュメントなどには、The SPE Runtime Management Library などと呼称されている。
このライブラリでは、SPEにアクセスするための標準化されたローレベルのAPIが提供されている。
目次 |
[編集] libspe とは
SPEは計算に特化したコアであり、PPEの助け無しにはプログラムの読み込みすら出来ない設計になっている。 そのため、PPEのプログラムは、SPEに対してプログラムのロードや実行開始の指示などを行ってやる必要がある。
libspeは、これらのPPEがSPEに対して行う操作を補助するためのライブラリである。(つまり、libspeはPPEが使用するライブラリである。SPEのプログラムにリンクするライブラリでは無いので注意)
[編集] libspe と libspe2
libspeには、APIに互換性の無い Ver 1.x 系列と Ver 2.x 系列の2種類が存在する。 Ver 2 系列では、ヘッダやライブラリのファイル名が libspe2.h, libspe2.so などとなっており、Ver 1 系列の物と明示的に区別されている。
単に libspe と呼称した場合、狭義には Ver 1.x 系列のみを指し、広義には両系列を合わせた総称を指す。
本wikiでは、より細かい操作ができ、新しいバージョンでもある Ver 2.x 系列のAPIを基本として扱う。
[編集] 入手方法
libspe は、Ver 1.x 系列も Ver 2.x 系列もCell SDKとして配布されている。ただし、現在の Cell SDK 2.0 で配布されている libspe2-2.0.1 には、SPEに引数が正しく渡らないなど、致命的なバグが幾つも見つかっているので、PS3 Linux Distributor's Starter Kit 1.1 に含まれる libspe2-2.0.1-be0647.3.20061130.1.ps3pf の方を使用したほうが良い。
libspe2 のAPIドキュメントは、PS3 Linux Distributor's Starter Kit 1.1 に同梱して配布されている。(doc/libspe-v2.0.pdf)
[編集] ヘッダとライブラリのファイル名
ヘッダファイル名は "libspe2.h"。ライブラリファイル名は "libspe2.a", "libspe2.so" なので、リンク時にはリンカに "-lspe2" オプションを追加する。
[編集] APIクイックリファレンス
以下に libspe2 の関数のリストと、引数等の簡易説明を示す。詳細な解説は各関数/構造体/用語からリンクされている先のページを参照。
[編集] SPEコンテキスト
SPU用のスレッドのようなもの。
これをCreateし、プログラムをロードし、Runさせれば実行できる。
spe_context_ptr_t spe_context_create ( unsigned int flags, /* [in] フラグのビットOR。0でいい */ spe_gang_context_ptr_t gang) /* [in] ギャングコンテキストを指定。無用ならNULLでいい */ /* [ret] 失敗時: NULL を返しerrnoを設定 */
int spe_context_destroy ( spe_context_ptr_t spe) /* [in] */ /* [ret] 成功時: 0 失敗時: -1 を返しerrnoを設定 */
[編集] SPEギャングコンテキスト
複数のSPEコンテキストをひとかたまりとして扱う機構。（未実装？）
spe_gang_context_ptr_t spe_gang_context_create (unsigned int flags) int spe_gang_context_destroy (spe_gang_context_ptr_t gang)
[編集] SPEプログラムイメージハンドル
SPE用のプログラムは、まずファイルから読み出したうえで、SPEコンテキストにロードしなければならない。
ファイルから読み出すのが spe_image_open()、コンテキストにロードするのが spe_program_load()。 つまりファイルからの"ロード"は"Open"なので注意。
spe_program_handle_t * spe_image_open ( const char *filename) /* [in] 読み込むSPE ELFファイルのファイル名(パス) */ /* [ret] 失敗時: NULL を返しerrnoを設定 */
int spe_image_close ( spe_program_handle_t *program) /* [in] */ /* [ret] 成功時: 0 失敗時: -1 を返しerrnoを設定 */
int spe_program_load ( spe_context_ptr_t spe, /* [in] プログラムを読み込ませたいSPEコンテキスト */ spe_program_handle_t *program) /* [in] 読み込ませたいプログラムイメージハンドル */ /* [ret] 成功時: 0 失敗時: -1 を返しerrnoを設定 */
[編集] SPEの実行
SPEコンテキストの実行には spe_context_run() を使う。この関数は何らかの理由でSPEが停止するまで戻ってこない。
エラーで停止したか、正常終了したかは、戻り値とstopinfoで判断できる。
int spe_context_run ( spe_context_ptr_t spe, /* [in] 実行開始させたいSPEコンテキスト */ unsigned int *entry, /* [in/out] 実行開始アドレスを格納した変数へのポインタ。 ポインタ先の変数には SPE_DEFAULT_ENTRY を入れておく */ unsigned int runflags, /* [in] ビットORのフラグ。 0でいい */ void *argp, /* [in] SPEのmain関数に渡される引数 */ void *envp, /* [in] SPEのmain関数に渡される引数 */ spe_stop_info_t *stopinfo) /* [out] 停止理由が格納される。無用ならNULLでいい */ /* [ret] 0: SPEがexit()を呼んで正常終了した */ /* 正の値: stop and signalで停止した */ /* -1: 実行に失敗した */
int spe_stop_info_read ( spe_context_ptr_t spe, /* [in] Runした後止まったSPEコンテキスト */ spe_stop_info_t *stopinfo) /* [out] 停止理由が格納される */ /* [ret] 成功時: 0 失敗時: -1 を返しerrnoを設定 */
(以下、執筆中)
[編集] SPEイベント
複数のSPEイベント(例えばメールボックスの到着やDMAの転送完了など)をまとめて待つことが出来る機構。
createでハンドルを作成後、そのハンドルに、待ちたいイベントを全てregisterして、waitすると、いずれかのイベントが起こるまで待つことができる。
spe_event_handler_ptr_t spe_event_handler_create(void)
int spe_event_handler_destroy( spe_event_handler_ptr_t evhandler)
int spe_event_handler_register( spe_event_handler_ptr_t evhandler, spe_event_unit_t *event)
int spe_event_handler_deregister( spe_event_handler_ptr_t evhandler, spe_event_unit_t *event)
int spe_event_wait( spe_event_handler_ptr_t evhandler, spe_event_unit_t *events, int max_events, int timeout)
[編集] SPE MFC機構
[編集] SPE MFC プロキシ・コマンド
spe_mfcio_put, spe_mfcio_putb, spe_mfcio_putf spe_mfcio_get, spe_mfcio_getb, spe_mfcio_getf
[編集] SPE MFC プロキシ・タググループ完了機構
spe_mfcio_tag_status_read
[編集] SPE メールボックス機構
spe_out_mbox_read, spe_out_mbox_status spe_in_mbox_write, spe_in_mbox_status spe_out_intr_mbox_read, spe_out_intr_mbox_status
[編集] SPE SPUシグナル通知機構
spe_signal_write
