draft/man2/spu_run.2

   1 .\" Copyright (c) International Business Machines Corp., 2006
   2 .\"
   3 .\" This program is free software; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  11 .\" the GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program; if not, write to the Free Software
  15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  16 .\" MA 02111-1307 USA
  17 .\"
  18 .\" HISTORY:
  19 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
  20 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
  21 .\" 2007-07-10, some polishing by mtk
  22 .\" 2007-09-28, updates for newer kernels, added example
  23 .\"             by Jeremy Kerr <jk@ozlabs.org>
  24 .\"
  25 .\"*******************************************************************
  26 .\"
  27 .\" This file was generated with po4a. Translate the source file.
  28 .\"
  29 .\"*******************************************************************
  30 .TH SPU_RUN 2 2007\-11\-25 Linux "Linux Programmer's Manual"
  31 .SH 名前
  32 spu_run \- SPU コンテキストを実行する
  33 .SH 書式
  34 .nf
  35 \fB#include <sys/spu.h>\fP
  36
  37 \fBint spu_run(int \fP\fIfd\fP\fB, unsigned int *\fP\fInpc\fP\fB, unsigned int *\fP\fIevent\fP\fB);\fP
  38 .fi
  39 .SH 説明
  40 \fBspu_run\fP()  システムコールは、Cell Broadband Engine アーキテクチャを実装した PowerPC マシンで
  41 Synergistic Processor Units (SPU) にアクセスするために 使用される。 \fIfd\fP 引き数は、
  42 \fBspu_create\fP(2)  が返すファイルディスクリプタで、 特定の SPU コンテキストを参照する。 そのコンテキストが物理 SPU
  43 に割り当てられると、 \fInpc\fP で渡された命令ポインタ (instruction pointer) から実行が開始される。
  44
  45 SPU コードの実行は同期的 (synchronously) に行われる、つまり SPU が実行中は \fBspu_run\fP()  は停止 (block)
  46 する。 SPU コードの実行をメイン CPU や他の SPU と並行して行う必要がある場合は、 最初に、その SPU
  47 コードを実行する新しいスレッドを、(例えば \fBpthread_create\fP(3)  などを使って) 生成しなければならない。
  48
  49 \fBspu_run\fP()  が返るときには、SPU のプログラムカウンタの現在値が \fInpc\fP に書き込まれる。 これにより、連続する
  50 \fBspu_run\fP()  の呼び出しで同じ \fInpc\fP ポインタを使うことができる。
  51
  52 \fIevent\fP 引き数には、拡張ステータスコード用のバッファを指定する。 \fBSPU_CREATE_EVENTS_ENABLED\fP フラグ付きで
  53 SPU コンテキストが作成されると、 \fBspu_run\fP()  が返る前に Linux カーネルによりこのバッファに
  54 拡張ステータスコードが格納される。
  55
  56 ステータスコードには以下の定数が一つ以上入る。
  57 .TP
  58 \fBSPE_EVENT_DMA_ALIGNMENT\fP
  59 DMA (direct memory access) のアライメント・エラーが発生した。
  60 .TP
  61 \fBSPE_EVENT_INVALID_DMA\fP
  62 無効な MFC (Memory Flow Controller) DMA コマンドを行おうとした。
  63 .TP
  64 \fBSPE_EVENT_SPE_DATA_STORAGE\fP
  65 DMA ストレージ・エラーが発生した。
  66 .TP
  67 \fBSPE_EVENT_SPE_ERROR\fP
  68 不正な命令が実行された。
  69 .PP
  70 NULL は \fIevent\fP 引き数として有効な値である。 この場合、イベントは呼び出し元のプロセスに報告されない。
  71 .SH 返り値
  72 成功すると、 \fBspu_run\fP()  は \fIspu_status\fP レジスタの値を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
  73 を下記のエラーコードのいずれかに設定する。
  74
  75 \fIspu_status\fP レジスタの値は、ステータスコードと SPU の \fBstop\-and\-signal\fP 命令が返す 14 ビットのコードの
  76 ビットマスクで構成される。 後者の 14 ビットのコードはオプションである。 ステータスコードのビットマスクは下記の通りである。
  77 .TP
  78 \fB0x02\fP
  79 SPU が \fBstop\-and\-signal\fP 命令で停止した。
  80 .TP
  81 \fB0x04\fP
  82 SPU が \fBhalt (停止)\fP 命令で止まった。
  83 .TP
  84 \fB0x08\fP
  85 SPU はチャンネルのウェイト中である。
  86 .TP
  87 \fB0x10\fP
  88 SPU はシングルステップモードであった。
  89 .TP
  90 \fB0x20\fP
  91 SPU が不正な命令を実行しようとした。
  92 .TP
  93 \fB0x40\fP
  94 SPU が不正なチャンネルにアクセスしようとした。
  95 .TP
  96 \fB0x3fff0000\fP
  97 この値のマスクを適用して得られたビット値には、 stop\-and\-signal 命令から返されたコードが入っている。 これらのビットは 0x02
  98 ビットがセットされている場合にのみ有効である。
  99 .PP
 100 \fBspu_run\fP()  がエラーを返さなかった場合、下位 8 ビットのうち 1 つ以上は 常にセットされる。
 101 .SH エラー
 102 .TP
 103 \fBEBADF\fP
 104 \fIfd\fP が有効なファイルディスクリプタでない。
 105 .TP
 106 \fBEFAULT\fP
 107 \fInpc\fP が有効なポインタでない。または \fIevent\fP が NULL 以外で、しかも無効なポインタである。
 108 .TP
 109 \fBEINTR\fP
 110 \fBspu_run\fP()  の実行中にシグナルが発生した。 \fBsignal\fP(7)  参照。 必要であれば、 \fInpc\fP
 111 の値は新しいプログラムカウンタの値に更新される。
 112 .TP
 113 \fBEINVAL\fP
 114 \fIfd\fP が \fBspu_create\fP(2)  が返した有効なファイルディスクリプタでない。
 115 .TP
 116 \fBENOMEM\fP
 117 Memory Flow Controller (MFC) DMA により発生したページフォールトを 処理するのに必要なメモリがなかった。
 118 .TP
 119 \fBENOSYS\fP
 120 機能が動作中のシステムで提供されていない。理由は、 ハードウェアで SPU が提供されていないか、 spufs
 121 モジュールがロードされていないか、のどちらかである。
 122 .SH バージョン
 123 \fBspu_run\fP()  システムコールはカーネル 2.6.16 で Linux に追加された。
 124 .SH 準拠
 125 このシステムコールは Linux 固有であり、 PowerPC アーキテクチャでのみ実装されている。
 126 このシステムコールを使ったプログラムは移植性がない。
 127 .SH 注意
 128 glibc はこのシステムコールに対するラッパー関数を提供していない。 \fBsyscall\fP(2)  を使うこと。ただし、 \fBspu_run\fP()
 129 は より抽象度の高い SPU へのインタフェースを実装するライブラリから 利用されることを意図したものであり、通常のアプリケーションから
 130 使用は意図されていない。推奨のライブラリについては
 131 \fIhttp://www.bsc.es/projects/deepcomputing/linuxoncell/\fP を参照のこと。
 132 .SH 例
 133 以下は、簡単な 1 命令の SPU プログラムを \fBspu_run\fP()  システムコールを使って実行させる例である。
 134
 135 .nf
 136 #include <stdlib.h>
 137 #include <stdint.h>
 138 #include <unistd.h>
 139 #include <stdio.h>
 140 #include <sys/types.h>
 141 #include <fcntl.h>
 142
 143 #define handle_error(msg) \e
 144     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 145
 146 int main(void)
 147 {
 148     int context, fd, spu_status;
 149     uint32_t instruction, npc;
 150
 151     context = spu_create("/spu/example\-context", 0, 0755);
 152     if (context == \-1)
 153         handle_error("spu_create");
 154
 155     /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
 156      * local store memory
 157      */
 158     instruction = 0x00001234;
 159
 160     fd = open("/spu/example\-context/mem", O_RDWR);
 161     if (fd == \-1)
 162         handle_error("open");
 163     write(fd, &instruction, sizeof(instruction));
 164
 165     /* set npc to the starting instruction address of the
 166      * SPU program. Since we wrote the instruction at the
 167      * start of the mem file, the entry point will be 0x0
 168      */
 169     npc = 0;
 170
 171     spu_status = spu_run(context, &npc, NULL);
 172     if (spu_status == \-1)
 173         handle_error("open");
 174
 175     /* we should see a status code of 0x1234002:
 176      *   0x00000002 (spu was stopped due to stop\-and\-signal)
 177      * | 0x12340000 (the stop\-and\-signal code)
 178      */
 179     printf("SPU Status: 0x%08x\en", spu_status);
 180
 181     exit(EXIT_SUCCESS);
 182 }
 183 .fi
 184 .\" .SH AUTHORS
 185 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 186 .SH 関連項目
 187 \fBclose\fP(2), \fBspu_create\fP(2), \fBcapabilities\fP(7), \fBspufs\fP(7)