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 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  26 .\"         all rights reserved.
  27 .\" Translated 2007-10-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  28 .\" Updated 2008-11-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.04
  29 .\"
  30 .TH SPU_RUN 2 2007-11-25 Linux "Linux Programmer's Manual"
  31 .\"O .SH NAME
  32 .SH 名前
  33 .\"O spu_run \- execute an SPU context
  34 spu_run \- SPU コンテキストを実行する
  35 .\"O .SH SYNOPSIS
  36 .SH 書式
  37 .nf
  38 .B #include <sys/spu.h>
  39
  40 .BI "int spu_run(int " fd ", unsigned int *" npc \
  41 ", unsigned int *" event ");"
  42 .fi
  43 .\"O .SH DESCRIPTION
  44 .SH 説明
  45 .\"O The
  46 .\"O .BR spu_run ()
  47 .\"O system call is used on PowerPC machines that implement the
  48 .\"O Cell Broadband Engine Architecture in order to access Synergistic
  49 .\"O Processor Units (SPUs).
  50 .\"O The
  51 .\"O .I fd
  52 .\"O argument is a file descriptor returned by
  53 .\"O .BR spu_create (2)
  54 .\"O that refers to a specific SPU context.
  55 .\"O When the context gets scheduled to a physical SPU,
  56 .\"O it starts execution at the instruction pointer passed in
  57 .\"O .IR npc .
  58 .BR spu_run ()
  59 システムコールは、Cell Broadband Engine アーキテクチャを実装した
  60 PowerPC マシンで Synergistic Processor Units (SPU) にアクセスするために
  61 使用される。
  62 .I fd
  63 引き数は、
  64 .BR spu_create (2)
  65 が返すファイルディスクリプタで、
  66 特定の SPU コンテキストを参照する。
  67 そのコンテキストが物理 SPU に割り当てられると、
  68 .I npc
  69 で渡された命令ポインタ (instruction pointer) から実行が開始される。
  70
  71 .\"O Execution of SPU code happens synchronously, meaning that
  72 .\"O .BR spu_run ()
  73 .\"O blocks while the SPU is still running.
  74 .\"O If there is a need
  75 .\"O to execute SPU code in parallel with other code on either the
  76 .\"O main CPU or other SPUs, a new thread of execution must be created
  77 .\"O first (e.g., using
  78 .\"O .BR pthread_create (3)).
  79 SPU コードの実行は同期的 (synchronously) に行われる、つまり
  80 SPU が実行中は
  81 .BR spu_run ()
  82 は停止 (block) する。
  83 SPU コードの実行をメイン CPU や他の SPU と並行して行う必要がある場合は、
  84 最初に、その SPU コードを実行する新しいスレッドを、(例えば
  85 .BR pthread_create (3)
  86 などを使って) 生成しなければならない。
  87
  88 .\"O When
  89 .\"O .BR spu_run ()
  90 .\"O returns, the current value of the SPU program counter is written to
  91 .\"O .IR npc ,
  92 .\"O so successive calls to
  93 .\"O .BR spu_run ()
  94 .\"O can use the same
  95 .\"O .I npc
  96 .\"O pointer.
  97 .BR spu_run ()
  98 が返るときには、SPU のプログラムカウンタの現在値が
  99 .I npc
 100 に書き込まれる。
 101 これにより、連続する
 102 .BR spu_run ()
 103 の呼び出しで同じ
 104 .I npc
 105 ポインタを使うことができる。
 106
 107 .\"O The
 108 .\"O .I event
 109 .\"O argument provides a buffer for an extended status code.
 110 .\"O If the SPU
 111 .\"O context was created with the
 112 .\"O .B SPU_CREATE_EVENTS_ENABLED
 113 .\"O flag, then this buffer is populated by the Linux kernel before
 114 .\"O .BR spu_run ()
 115 .\"O returns.
 116 .I event
 117 引き数には、拡張ステータスコード用のバッファを指定する。
 118 .B SPU_CREATE_EVENTS_ENABLED
 119 フラグ付きで SPU コンテキストが作成されると、
 120 .BR spu_run ()
 121 が返る前に Linux カーネルによりこのバッファに
 122 拡張ステータスコードが格納される。
 123
 124 .\"O The status code may be one (or more) of the following constants:
 125 ステータスコードには以下の定数が一つ以上入る。
 126 .TP
 127 .B SPE_EVENT_DMA_ALIGNMENT
 128 .\"O A DMA alignment error occurred.
 129 DMA (direct memory access) のアライメント・エラーが発生した。
 130 .TP
 131 .B SPE_EVENT_INVALID_DMA
 132 .\"O An invalid MFC DMA command was attempted.
 133 無効な MFC (Memory Flow Controller) DMA コマンドを行おうとした。
 134 .TP
 135 .B SPE_EVENT_SPE_DATA_STORAGE
 136 .\"O A DMA storage error occurred.
 137 DMA ストレージ・エラーが発生した。
 138 .TP
 139 .B SPE_EVENT_SPE_ERROR
 140 .\"O An illegal instruction was executed.
 141 不正な命令が実行された。
 142 .PP
 143 .\"O NULL
 144 .\"O is a valid value for the
 145 .\"O .I event
 146 .\"O argument.
 147 .\"O In this case, the events will not be reported to the calling process.
 148 NULL は
 149 .I event
 150 引き数として有効な値である。
 151 この場合、イベントは呼び出し元のプロセスに報告されない。
 152 .\"O .SH RETURN VALUE
 153 .SH 返り値
 154 .\"O On success,
 155 .\"O .BR spu_run ()
 156 .\"O returns the value of the
 157 .\"O .I spu_status
 158 .\"O register.
 159 .\"O On error it returns \-1 and sets
 160 .\"O .I errno
 161 .\"O to one of the error codes listed below.
 162 成功すると、
 163 .BR spu_run ()
 164 は
 165 .I spu_status
 166 レジスタの値を返す。
 167 エラーの場合、\-1 を返し、
 168 .I errno
 169 を下記のエラーコードのいずれかに設定する。
 170
 171 .\"O The
 172 .\"O .I spu_status
 173 .\"O register value is a bit mask of status codes and
 174 .\"O optionally a 14-bit code returned from the
 175 .\"O .BR stop-and-signal
 176 .\"O instruction on the SPU.
 177 .\"O The bit masks for the status codes
 178 .\"O are:
 179 .I spu_status
 180 レジスタの値は、ステータスコードと SPU の
 181 .B stop-and-signal
 182 命令が返す 14 ビットのコードの
 183 ビットマスクで構成される。
 184 後者の 14 ビットのコードはオプションである。
 185 ステータスコードのビットマスクは下記の通りである。
 186 .TP
 187 .B 0x02
 188 .\"O SPU was stopped by a
 189 .\"O .BR stop-and-signal
 190 .\"O instruction.
 191 SPU が
 192 .B stop-and-signal
 193 命令で停止した。
 194 .TP
 195 .B 0x04
 196 .\"O SPU was stopped by a
 197 .\"O .BR halt
 198 .\"O instruction.
 199 SPU が
 200 .B "halt (停止)"
 201 命令で止まった。
 202 .TP
 203 .B 0x08
 204 .\"O SPU is waiting for a channel.
 205 SPU はチャンネルのウェイト中である。
 206 .TP
 207 .B 0x10
 208 .\"O SPU is in single-step mode.
 209 SPU はシングルステップモードであった。
 210 .TP
 211 .B 0x20
 212 .\"O SPU has tried to execute an invalid instruction.
 213 SPU が不正な命令を実行しようとした。
 214 .TP
 215 .B 0x40
 216 .\"O SPU has tried to access an invalid channel.
 217 SPU が不正なチャンネルにアクセスしようとした。
 218 .TP
 219 .B 0x3fff0000
 220 .\"O The bits masked with this value contain the code returned from a
 221 .\"O .BR stop-and-signal
 222 .\"O instruction.
 223 .\"O These bits are only valid if the 0x02 bit is set.
 224 この値のマスクを適用して得られたビット値には、
 225 stop-and-signal 命令から返されたコードが入っている。
 226 これらのビットは 0x02 ビットがセットされている場合にのみ有効である。
 227 .PP
 228 .\"O If
 229 .\"O .BR spu_run ()
 230 .\"O has not returned an error, one or more bits among the lower eight
 231 .\"O ones are always set.
 232 .BR spu_run ()
 233 がエラーを返さなかった場合、下位 8 ビットのうち 1 つ以上は
 234 常にセットされる。
 235 .\"O .SH ERRORS
 236 .SH エラー
 237 .TP
 238 .B EBADF
 239 .\"O .I fd
 240 .\"O is not a valid file descriptor.
 241 .I fd
 242 が有効なファイルディスクリプタでない。
 243 .TP
 244 .B EFAULT
 245 .\"O .I npc
 246 .\"O is not a valid pointer, or
 247 .\"O .I event
 248 .\"O is non-NULL and an invalid pointer.
 249 .I npc
 250 が有効なポインタでない。または
 251 .I event
 252 が NULL 以外で、しかも無効なポインタである。
 253 .TP
 254 .B EINTR
 255 .\"O A signal occurred while
 256 .\"O .BR spu_run ()
 257 .\"O was in progress; see
 258 .\"O .BR signal (7).
 259 .\"O The
 260 .\"O .I npc
 261 .\"O value has been updated to the new program counter value if
 262 .\"O necessary.
 263 .BR spu_run ()
 264 の実行中にシグナルが発生した。
 265 .BR signal (7)
 266 参照。
 267 必要であれば、
 268 .I npc
 269 の値は新しいプログラムカウンタの値に更新される。
 270 .TP
 271 .B EINVAL
 272 .\"O .I fd
 273 .\"O is not a valid file descriptor returned from
 274 .\"O .BR spu_create (2).
 275 .I fd
 276 が
 277 .BR spu_create (2)
 278 が返した有効なファイルディスクリプタでない。
 279 .TP
 280 .B ENOMEM
 281 .\"O There was not enough memory available to handle a page fault
 282 .\"O resulting from a Memory Flow Controller (MFC) direct memory access.
 283 Memory Flow Controller (MFC) DMA により発生したページフォールトを
 284 処理するのに必要なメモリがなかった。
 285 .TP
 286 .B ENOSYS
 287 .\"O The functionality is not provided by the current system, because
 288 .\"O either the hardware does not provide SPUs or the spufs module is not
 289 .\"O loaded.
 290 機能が動作中のシステムで提供されていない。理由は、
 291 ハードウェアで SPU が提供されていないか、
 292 spufs モジュールがロードされていないか、のどちらかである。
 293 .\"O .SH VERSIONS
 294 .SH バージョン
 295 .\"O The
 296 .\"O .BR spu_run ()
 297 .\"O system call was added to Linux in kernel 2.6.16.
 298 .BR spu_run ()
 299 システムコールはカーネル 2.6.16 で Linux に追加された。
 300 .\"O .SH CONFORMING TO
 301 .SH 準拠
 302 .\"O This call is Linux-specific and only implemented by the PowerPC
 303 .\"O architecture.
 304 .\"O Programs using this system call are not portable.
 305 このシステムコールは Linux 固有であり、
 306 PowerPC アーキテクチャでのみ実装されている。
 307 このシステムコールを使ったプログラムは移植性がない。
 308 .\"O .SH NOTES
 309 .SH 注意
 310 .\"O Glibc does not provide a wrapper for this system call; call it using
 311 .\"O .BR syscall (2).
 312 .\"O Note however, that
 313 .\"O .BR spu_run ()
 314 .\"O is meant to be used from libraries that implement a more abstract
 315 .\"O interface to SPUs, not to be used from regular applications.
 316 .\"O See
 317 .\"O .I http://www.bsc.es/projects/deepcomputing/linuxoncell/
 318 .\"O for the recommended libraries.
 319 glibc はこのシステムコールに対するラッパー関数を提供していない。
 320 .BR syscall (2)
 321 を使うこと。ただし、
 322 .BR spu_run ()
 323 は より抽象度の高い SPU へのインタフェースを実装するライブラリから
 324 利用されることを意図したものであり、通常のアプリケーションから
 325 使用は意図されていない。推奨のライブラリについては
 326 .I http://www.bsc.es/projects/deepcomputing/linuxoncell/
 327 を参照のこと。
 328 .\"O .SH EXAMPLE
 329 .SH 例
 330 .\"O The following is an example of running a simple, one-instruction SPU
 331 .\"O program with the
 332 .\"O .BR spu_run ()
 333 .\"O system call.
 334 以下は、簡単な 1 命令の SPU プログラムを
 335 .BR spu_run ()
 336 システムコールを使って実行させる例である。
 337
 338 .nf
 339 #include <stdlib.h>
 340 #include <stdint.h>
 341 #include <unistd.h>
 342 #include <stdio.h>
 343 #include <sys/types.h>
 344 #include <fcntl.h>
 345
 346 #define handle_error(msg) \\
 347     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 348
 349 int main(void)
 350 {
 351     int context, fd, spu_status;
 352     uint32_t instruction, npc;
 353
 354     context = spu_create("/spu/example\-context", 0, 0755);
 355     if (context == \-1)
 356         handle_error("spu_create");
 357
 358     /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
 359      * local store memory
 360      */
 361     instruction = 0x00001234;
 362
 363     fd = open("/spu/example\-context/mem", O_RDWR);
 364     if (fd == \-1)
 365         handle_error("open");
 366     write(fd, &instruction, sizeof(instruction));
 367
 368     /* set npc to the starting instruction address of the
 369      * SPU program. Since we wrote the instruction at the
 370      * start of the mem file, the entry point will be 0x0
 371      */
 372     npc = 0;
 373
 374     spu_status = spu_run(context, &npc, NULL);
 375     if (spu_status == \-1)
 376         handle_error("open");
 377
 378     /* we should see a status code of 0x1234002:
 379      *   0x00000002 (spu was stopped due to stop\-and\-signal)
 380      * | 0x12340000 (the stop\-and\-signal code)
 381      */
 382     printf("SPU Status: 0x%08x\\n", spu_status);
 383
 384     exit(EXIT_SUCCESS);
 385 }
 386 .fi
 387 .\" .SH AUTHORS
 388 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 389 .\"O .SH SEE ALSO
 390 .SH 関連項目
 391 .BR close (2),
 392 .BR spu_create (2),
 393 .BR capabilities (7),
 394 .BR spufs (7)