draft/man2/spu_run.2

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