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