release/man7/spufs.7

   1 .\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
   2 .\"
   3 .\" Copyright (c) International Business Machines Corp., 2006
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" This program is distributed in the hope that it will be useful,
  11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  13 .\" the GNU General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public License
  16 .\" along with this program; if not, write to the Free Software
  17 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  18 .\" MA 02111-1307 USA
  19 .\"
  20 .\" HISTORY:
  21 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>,
  22 .\"   Mark Nutter <mnutter@us.ibm.com> and
  23 .\"   Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
  24 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
  25 .\" 2007-07-10, quite a lot of polishing by mtk
  26 .\"
  27 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  28 .\"         all rights reserved.
  29 .\" Translated 2007-10-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  30 .\"
  31 .TH SPUFS 7 2007-07-10 "Linux" "Linux Programmer's Manual"
  32 .SH 名前
  33 spufs \- SPU ファイルシステム
  34 .SH 説明
  35 SPU ファイルシステムは、Cell Broadband Engine アーキテクチャを実装した
  36 PowerPC マシンにおいて、Synergistic Processor Unit (SPU) にアクセスする
  37 ために使用される。
  38
  39 このファイルシステムでは、POSIX 共有メモリやメッセージキューに
  40 似た名前空間が提供される。
  41 ファイルシステムに書き込み許可を持つユーザは
  42 .BR spu_create (2)
  43 を使って spufs のルートディレクトリに SPU コンテキストを作成できる。
  44
  45 各 SPU コンテキストは、あらかじめ定義されたファイル群を含む
  46 ディレクトリとして表現される。
  47 これらのファイルを使って、論理 SPU の状態を操作できる。
  48 ユーザはこれらのファイルのアクセス許可を変更することはできるが、
  49 ファイルの追加・削除を行うことはできない。
  50 .SS マウントオプション
  51 .TP
  52 .B uid=<uid>
  53 マウントポイントを所有するユーザを設定する。
  54 デフォルトは 0 (root) である。
  55 .TP
  56 .B gid=<gid>
  57 マウントポイントを所有するグループを設定する。
  58 デフォルトは 0 (root) である。
  59 .SS ファイル
  60 .I spufs
  61 のファイルは、ほとんどの場合
  62 .BR read (2)
  63 や
  64 .BR write (2)
  65 といった通常のシステムコールに対する標準的な振る舞いを示すが、
  66 多くの場合通常のファイルシステムでサポートされている操作の一部分だけが
  67 サポートされている。以下のリストでは、サポートされている操作と
  68 それぞれのマニュアルページに書かれている標準的な振る舞いとの違いに
  69 ついて説明する。
  70
  71 .BR read (2)
  72 操作に対応している全てのファイルは
  73 .BR readv (2)
  74 にも対応している。また、
  75 .BR write (2)
  76 操作に対応している全てのファイルは
  77 .BR writev (2)
  78 にも対応している。
  79
  80 全てのファイルは、
  81 .BR access (2)
  82 と
  83 .BR stat (2)
  84 系の操作に対応しているが、
  85 .BR stat (2)
  86 では、呼び出した際に返される
  87 .I stat
  88 構造体のフィールドのうち信頼できる情報が入っているのは
  89 .IR st_mode ,
  90 .IR st_nlink ,
  91 .IR st_uid ,
  92 .I st_gid
  93 だけである。
  94
  95 全てのファイルは
  96 .BR chmod (2)/ fchmod (2)
  97 と
  98 .BR chown (2)/ fchown (2)
  99 の操作に対応しているが、
 100 そのファイルが対応している操作と矛盾するアクセス許可を
 101 付与することはできない (例えば、
 102 .I wbox
 103 ファイルに対する読み出しアクセスなど)。
 104
 105 現時点でのファイルは以下の通りである。
 106 .TP
 107 .B /mem
 108 SPU のローカルストレージの内容。
 109 このファイルは通常の共有メモリファイルと同様にアクセスでき、
 110 SPU のアドレス空間にはコードとデータの両方を格納できる。
 111 オープンされた
 112 .I mem
 113 ファイルに可能な操作は以下である。
 114 .RS
 115 .TP
 116 .BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2)
 117 これらは通常通り動作するが、
 118 ファイル末尾を越えての
 119 .BR lseek (2),
 120 .BR write (2),
 121 .BR pwrite (2)
 122 に対応していない点だけが異なる。
 123 ファイルサイズは SPU のローカルストレージのサイズであり、
 124 通常は 256 キロバイトである。
 125 .TP
 126 .BR mmap (2)
 127 .I mem
 128 をプロセスのアドレス空間にマッピングすると、
 129 プロセスのアドレス空間の一部として
 130 SPU のローカル・ストレージにアクセスできるようになる。
 131 .RE
 132 .TP
 133 .B /mbox
 134 SPU から CPU への通信用の一つ目のメールボックス。
 135 このファイルは読み出し専用で、読み出しは 32ビット単位で行う。
 136 このファイルは非停止 (non-blocking) モードでのみ使用でき、
 137 .BR poll (2)
 138 であってもこのファイルで停止 (block) することはない。
 139 オープンされた
 140 .I mbox
 141 ファイルに可能な操作は以下である。
 142 .RS
 143 .TP
 144 .BR read (2)
 145 .I count
 146 が 4 より小さい場合、
 147 .BR read (2)
 148 は \-1 を返し、
 149 .I errno
 150 を
 151 .B EINVAL
 152 に設定する。
 153 メールボックスにデータがない場合、\-1 が返り、
 154 .I errno
 155 が
 156 .B EAGAIN
 157 に設定される。データの読み出しに成功した場合、
 158 4 バイトがデータバッファに格納され、返り値として 4 が返される。
 159 .RE
 160 .TP
 161 .B /ibox
 162 SPU から CPU への通信用の二つ目のメールボックスである。
 163 このファイルは一つ目のメールボックスファイルと似ているが、
 164 停止 (blocking) I/O モードでの読み出しが可能である。したがって、
 165 .BR poll (2)
 166 や同様のシステムコールを使って、このファイルを監視することができる。
 167 オープンされた
 168 .I ibox
 169 ファイルに可能な操作は以下である。
 170 .RS
 171 .TP
 172 .BR read (2)
 173 .I count
 174 が 4 より小さい場合、
 175 .BR read (2)
 176 は \-1 を返し、
 177 .I errno
 178 を
 179 .B EINVAL
 180 に設定する。
 181 メールボックスにデータがない場合、ファイルディスクリプタが
 182 .B O_NONBLOCK
 183 でオープンされていれば、返り値は \-1 となり、
 184 .I errno
 185 は
 186 .B EAGAIN
 187 に設定される。
 188
 189 メールボックスにデータがない場合で、ファイルディスクリプタが
 190 .B O_NONBLOCK
 191 なしでオープンされていれば、
 192 SPU が自分の割り込みメールボックスチャネル (interrupt mailbox channel)
 193 に書き込みを行うまで
 194 .BR read (2)
 195 は停止 (block) する。
 196 データの読み出しに成功した場合、
 197 4 バイトがデータバッファに格納され、返り値として 4 が返される。
 198 .TP
 199 .BR poll (2)
 200 .I ibox
 201 ファイルに対する
 202 .BR poll (2)
 203 は、読み出しデータが利用可能になる度に
 204 .I "(POLLIN | POLLRDNORM)"
 205 を返す。
 206 .RE
 207 .TP
 208 .B /wbox
 209 CPU から SPU への通信用のメールボックス。
 210 このファイルは書き込み専用で、書き込みは 32ビット単位で行う。
 211 メールボックスが一杯の場合、
 212 .BR write (2)
 213 は停止 (block) し、
 214 .BR poll (2)
 215 を使ってメールボックスに再度空きができるまで待つことができる。
 216 オープンされた
 217 .I wbox
 218 ファイルに可能な操作は以下である。
 219 .RS
 220 .TP
 221 .BR write (2)
 222 .I count
 223 が 4 より小さい場合、
 224 .BR write (2)
 225 は \-1 を返し、
 226 .I errno
 227 を
 228 .B EINVAL
 229 に設定する。
 230 メールボックスに空き領域がない場合、ファイルディスクリプタが
 231 .B O_NONBLOCK
 232 でオープンされていれば、返り値は \-1 となり、
 233 .I errno
 234 は
 235 .B EAGAIN
 236 に設定される。
 237
 238 メールボックスに空き領域がない場合で、ファイルディスクリプタが
 239 .B O_NONBLOCK
 240 なしでオープンされていれば、
 241 SPU が自分の PPE メールボックスチャネルから読み出しを行うまで
 242 .BR write (2)
 243 は停止 (block) する。
 244 データの書き込みに成功した場合、返り値として 4 が返される。
 245 .TP
 246 .BR poll (2)
 247 .I wbox
 248 ファイルに対する
 249 .BR poll (2)
 250 は、書き込み用の空間が利用可能になる度に
 251 .I "(POLLOUT | POLLWRNORM)"
 252 を返す。
 253 .RE
 254 .TP
 255 .BR /mbox_stat ", " /ibox_stat ", " /wbox_stat
 256 これらのファイルは読み出し専用で、
 257 各メールボックスの現在のキュー長を保持する。
 258 具体的には、停止 (blocking) せずに、
 259 .IR mbox " や " ibox
 260 から何ワードを読み出すことができ、
 261 .I wbox
 262 に何ワードを書き込むことができるか、ということである。
 263 これらのファイルは 4 バイト単位でのみ読み出しが可能で、
 264 ビッグ・エンディアンの整数値を返す。
 265 オープンされた
 266 .I *box_stat
 267 ファイルに可能な操作は以下である。
 268 .RS
 269 .TP
 270 .BR read (2)
 271 .I count
 272 が 4 より小さい場合、
 273 .BR read (2)
 274 は \-1 を返し、
 275 .I errno
 276 を
 277 .B EINVAL
 278 に設定する。
 279 それ以外の場合、データバッファに 4 バイトの値が書き込まれる。
 280 この値は、各メールボックスにおいて停止せずに、または
 281 .B EAGAIN
 282 エラーなしで、読み出し可能なエレメント数
 283 .RI ( mbox_stat
 284 や
 285 .I ibox_stat
 286 の場合)、書き込み可能なエレメント数
 287 .RI ( wbox_stat
 288 の場合) である。
 289 .RE
 290 .TP
 291 .BR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \
 292 /event_mask ", " /srr0
 293 これらのファイルは SPU の内部レジスタを公開するものである。
 294 値は、各レジスタの数値を含むアスキー文字列で表現される。
 295 これらのファイルはデバッグ用として読み出し/書き込みの両モードで利用できるが、
 296 プログラムの通常の操作はこれらのファイルに依存すべきではない。
 297 なぜなら、これらのファイルのうち
 298 .I npc
 299 以外へのアクセスでは SPU コンテキストの保存が必須であり、
 300 SPU コンテキストの保存は非常に効率が悪いからである。
 301 .IP
 302 これらのファイルの内容は以下の通り。
 303 .RS
 304 .TP 16
 305 .I npc
 306 次のプログラムカウンタ
 307 .TP
 308 .I decr
 309 SPU Decrementer
 310 .TP
 311 .I decr_status
 312 Decrementer の状態
 313 .TP
 314 .I spu_tag_mask
 315 SPU の DMA 用の MFA タグマスク
 316 .TP
 317 .I event_mask
 318 SPU の割り込みのイベントマスク
 319 .TP
 320 .I srr0
 321 割り込みリターンアドレスレジスタ
 322 .RE
 323 .IP
 324 これらのファイルに対して可能な操作は以下である。
 325 .RS
 326 .TP
 327 .BR read (2)
 328 .BR read (2)
 329 に渡された
 330 .I count
 331 がレジスタ値と改行 (newline) 文字 1 個を格納するのに必要な長さより短い場合、
 332 同じファイルディスクリプタを続けて read することで、文字列全体を読み出すこと
 333 ができる。この際、実行中の SPU タスクによりレジスタ値の変更の影響は受けない。
 334 文字列全体が読み出されると、それ以降の read 操作では 0 バイトが返され、
 335 新しい値を読み出すには新しいファイルディスクリプタをオープンする必要がある。
 336 .TP
 337 .BR write (2)
 338 このファイルへの
 339 .BR write (2)
 340 操作はレジスタ値を文字列で指定された値に設定する。
 341 文字列の解釈は先頭から開始され、数字以外の文字が初めて登場するか、
 342 バッファの末尾に達するまで行われる。
 343 同じファイルディスクリプタへ続けて write を行うと、
 344 後の write により前の設定が上書きされる。
 345 .RE
 346 .TP
 347 .B /fpcr
 348 このファイルにより Floating Point Status and Control Register に
 349 アクセスできる。このファイルは大きさ 4 バイトである。
 350 .I fpcr
 351 ファイルに可能な操作は以下である。
 352 .RS
 353 .TP
 354 .BR read (2)
 355 .I count
 356 が 4 より小さい場合、
 357 .BR read (2)
 358 は \-1 を返し、
 359 .I errno
 360 を
 361 .B EINVAL
 362 に設定する。
 363 それ以外の場合、データバッファに 4 バイトの値が書き込まれる。
 364 書き込まれる値は
 365 .I fpcr
 366 レジスタの現在の値である。
 367 .TP
 368 .BR write (2)
 369 .I count
 370 が 4 より小さい場合、
 371 .BR write (2)
 372 は \-1 を返し、
 373 .I errno
 374 を
 375 .B EINVAL
 376 に設定する。
 377 それ以外の場合、 4 バイトの値がデータバッファからコピーされ、
 378 .I fpcr
 379 レジスタの値が更新される。
 380 .RE
 381 .TP
 382 .BR /signal1 ", " /signal2
 383 これらのファイルにより
 384 SPU の二つのシグナル通知チャネル (signal notification channel) に
 385 アクセスできる。
 386 これらは 32 ビット単位の読み書きができる。
 387 これらのファイルの一つに書き込みを行うと、その SPU の割り込みが
 388 発生するトリガーとなる。
 389 シグナルファイルへ書き込まれた値は、チャネル経由で SPU で読み出したり、
 390 このファイル経由でホストのユーザ空間で読み出したりできる。
 391 SPU が値を読み出した後では、値は 0 にリセットされる。
 392 オープンされた
 393 .I signal1
 394 や
 395 .I signal2
 396 ファイルに可能な操作は以下である。
 397 .RS
 398 .TP
 399 .BR read (2)
 400 .I count
 401 が 4 より小さい場合、
 402 .BR read (2)
 403 は \-1 を返し、
 404 .I errno
 405 を
 406 .B EINVAL
 407 に設定する。
 408 それ以外の場合、データバッファに 4 バイトの値が書き込まれる。
 409 書き込まれる値は、指定されたシグナル通知レジスタの現在の値である。
 410 .TP
 411 .BR write (2)
 412 .I count
 413 が 4 より小さい場合、
 414 .BR write (2)
 415 は \-1 を返し、
 416 .I errno
 417 を
 418 .B EINVAL
 419 に設定する。
 420 それ以外の場合、 4 バイトの値がデータバッファからコピーされ、
 421 指定されたシグナル通知レジスタの値が更新される。
 422 シグナル通知レジスタの更新には、レジスタ値を入力データで置き換えるモードと
 423 以前の値と入力データのビット単位の OR をとった値に更新するモードがある。
 424 どちらのモードになるかは、それぞれ
 425 .IR signal1_type ,
 426 .I signal2_type
 427 ファイルの内容によって決まる。
 428 .RE
 429 .TP
 430 .BR /signal1_type ", " /signal2_type
 431 これらのファイルは、シグナル通知ファイル
 432 .I signal1
 433 と
 434 .I signal2
 435 の動作を変更する。
 436 これらのファイルは数値を表すアスキー文字列を保持し、
 437 読み出すと "1" か "0" のどちらかが得られる。
 438 モード 0 (上書きモード) では、ハードウェアはシグナルチャネルの内容を
 439 シグナルチャネルに書き込まれたデータで置き換える。
 440 モード 1 (論理 OR モード) では、ハードウェアはシグナルチャネルに
 441 書き込まれたビットを積算していく。
 442 オープンされた
 443 .I signal1_type
 444 や
 445 .I signal2_type
 446 ファイルに可能な操作は以下である。
 447 .RS
 448 .TP
 449 .BR read (2)
 450 .BR read (2)
 451 に渡された
 452 .I count
 453 がレジスタの数値と改行 (newline) 文字 1 個を格納するのに必要な長さより
 454 短い場合、同じファイルディスクリプタを続けて read することで、
 455 文字列全体を読み出すことができる。
 456 文字列全体が読み出されると、それ以降の read 操作では 0 バイトが返され、
 457 新しい値を読み出すには新しいファイルディスクリプタをオープンする必要がある。
 458 .TP
 459 .BR write (2)
 460 このファイルへの
 461 .BR write (2)
 462 操作はレジスタ値を文字列で指定された値に設定する。
 463 文字列の解釈は先頭から開始され、数字以外の文字が初めて登場するか、
 464 バッファの末尾に達するまで行われる。
 465 同じファイルディスクリプタへ続けて write を行うと、
 466 後の write により前の設定が上書きされる。
 467 .RE
 468 .SH 例
 469 .TP
 470 .IR /etc/fstab "  entry"
 471 none    /spu    spufs   gid=spu         0       0
 472 .\" .SH AUTHORS
 473 .\" Arnd Bergmann <arndb@de.ibm.com>,
 474 .\" Mark Nutter <mnutter@us.ibm.com> and
 475 .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
 476 .SH 関連項目
 477 .BR close (2),
 478 .BR spu_create (2),
 479 .BR spu_run (2)