original/man7/spufs.7

   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 .\"   Mark Nutter <mnutter@us.ibm.com> and
  21 .\"   Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
  22 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
  23 .\" 2007-07-10, quite a lot of polishing by mtk
  24 .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
  25 .\"
  26 .TH SPUFS 7 2007-12-20 Linux "Linux Programmer's Manual"
  27 .SH NAME
  28 spufs \- SPU file system
  29 .SH DESCRIPTION
  30 The SPU file system is used on PowerPC machines that implement the
  31 Cell Broadband Engine Architecture in order to access Synergistic
  32 Processor Units (SPUs).
  33
  34 The file system provides a name space similar to POSIX shared
  35 memory or message queues.
  36 Users that have write permissions
  37 on the file system can use
  38 .BR spu_create (2)
  39 to establish SPU contexts under the
  40 .B spufs
  41 root directory.
  42
  43 Every SPU context is represented by a directory containing
  44 a predefined set of files.
  45 These files can be
  46 used for manipulating the state of the logical SPU.
  47 Users can change permissions on the files, but can't
  48 add or remove files.
  49 .SS Mount Options
  50 .TP
  51 .B uid=<uid>
  52 Set the user owning the mount point; the default is 0 (root).
  53 .TP
  54 .B gid=<gid>
  55 Set the group owning the mount point; the default is 0 (root).
  56 .TP
  57 .B mode=<mode>
  58 Set the mode of the top-level directory in
  59 .BR spufs ,
  60 as an octal mode string.
  61 The default is 0775.
  62 .SS Files
  63 The files in
  64 .B spufs
  65 mostly follow the standard behavior for regular system calls like
  66 .BR read (2)
  67 or
  68 .BR write (2),
  69 but often support only a subset of the operations
  70 supported on regular file systems.
  71 This list details the supported
  72 operations and the deviations from the standard behavior described
  73 in the respective man pages.
  74
  75 All files that support the
  76 .BR read (2)
  77 operation also support
  78 .BR readv (2)
  79 and all files that support the
  80 .BR write (2)
  81 operation also support
  82 .BR writev (2).
  83 All files support the
  84 .BR access (2)
  85 and
  86 .BR stat (2)
  87 family of operations, but for the latter call,
  88 the only fields of the returned
  89 .I stat
  90 structure that contain reliable information are
  91 .IR st_mode ,
  92 .IR st_nlink ,
  93 .IR st_uid ,
  94 and
  95 .IR st_gid .
  96
  97 All files support the
  98 .BR chmod (2)/ fchmod (2)
  99 and
 100 .BR chown (2)/ fchown (2)
 101 operations, but will not be able to grant permissions that contradict
 102 the possible operations (e.g., read access on the
 103 .I wbox
 104 file).
 105
 106 The current set of files is:
 107 .TP
 108 .I /capabilities
 109 Contains a comma-delimited string representing the capabilities of this
 110 SPU context.
 111 Possible capabilities are:
 112 .RS
 113 .TP
 114 .B sched
 115 This context may be scheduled.
 116 .TP
 117 .B step
 118 This context can be run in single-step mode, for debugging.
 119 .PP
 120 New capabilities flags may be added in the future.
 121 .RE
 122 .TP
 123 .I /mem
 124 the contents of the local storage memory of the SPU.
 125 This can be accessed like a regular shared memory
 126 file and contains both code and data in the address
 127 space of the SPU.
 128 The possible operations on an open
 129 .I mem
 130 file are:
 131 .RS
 132 .TP
 133 .BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2)
 134 These operate as usual, with the exception that
 135 .BR lseek (2),
 136 .BR write (2),
 137 and
 138 .BR pwrite (2)
 139 are not supported beyond the end of the file.
 140 The file size
 141 is the size of the local storage of the SPU,
 142 which is normally 256 kilobytes.
 143 .TP
 144 .BR mmap (2)
 145 Mapping
 146 .I mem
 147 into the process address space provides access to the SPU local
 148 storage within the process address space.
 149 Only
 150 .B MAP_SHARED
 151 mappings are allowed.
 152 .RE
 153 .TP
 154 .I /regs
 155 Contains the saved general-purpose registers of the SPU context.
 156 This file contains the 128-bit values of each register,
 157 from register 0 to register 127, in order.
 158 This allows the general-purpose registers to be
 159 inspected for debugging.
 160
 161 Reading to or writing from this file requires that the context is
 162 scheduled out, so use of this file is not recommended in normal
 163 program operation.
 164
 165 The
 166 .I regs
 167 file is not present on contexts that have been created with the
 168 .B SPU_CREATE_NOSCHED
 169 flag.
 170 .TP
 171 .I /mbox
 172 The first SPU-to-CPU communication mailbox.
 173 This file is read-only and can be read in units of 4 bytes.
 174 The file can only be used in nonblocking mode \- even
 175 .BR poll (2)
 176 cannot be used to block on this file.
 177 The only possible operation on an open
 178 .I mbox
 179 file is:
 180 .RS
 181 .TP
 182 .BR read (2)
 183 If
 184 .I count
 185 is smaller than four,
 186 .BR read (2)
 187 returns \-1 and sets
 188 .I errno
 189 to
 190 .BR EINVAL .
 191 If there is no data available in the mailbox (i.e., the SPU has not
 192 sent a mailbox message), the return value is set to \-1 and
 193 .I errno
 194 is set to
 195 .BR EAGAIN .
 196 When data
 197 has been read successfully, four bytes are placed in
 198 the data buffer and the value four is returned.
 199 .RE
 200 .TP
 201 .I /ibox
 202 The second SPU-to-CPU communication mailbox.
 203 This file is similar to the first mailbox file, but can be read
 204 in blocking I/O mode, thus calling
 205 .BR read (2)
 206 on an open
 207 .I ibox
 208 file will block until the SPU has written data to its interrupt mailbox
 209 channel (unless the file has been opened with
 210 .BR O_NONBLOCK ,
 211 see below).
 212 Also,
 213 .BR poll (2)
 214 and similar system calls can be used to monitor for the presence
 215 of mailbox data.
 216
 217 The possible operations on an open
 218 .I ibox
 219 file are:
 220 .RS
 221 .TP
 222 .BR read (2)
 223 If
 224 .I count
 225 is smaller than four,
 226 .BR read (2)
 227 returns \-1 and sets
 228 .I errno
 229 to
 230 .BR EINVAL .
 231 If there is no data available in the mailbox and the file
 232 descriptor has been opened with
 233 .BR O_NONBLOCK ,
 234 the return value is set to \-1 and
 235 .I errno
 236 is set to
 237 .BR EAGAIN .
 238
 239 If there is no data available in the mailbox and the file
 240 descriptor has been opened without
 241 .BR O_NONBLOCK ,
 242 the call will
 243 block until the SPU writes to its interrupt mailbox channel.
 244 When data has been read successfully, four bytes are placed in
 245 the data buffer and the value four is returned.
 246 .TP
 247 .BR poll (2)
 248 Poll on the
 249 .I ibox
 250 file returns
 251 .I "(POLLIN | POLLRDNORM)"
 252 whenever data is available for reading.
 253 .RE
 254 .TP
 255 .I /wbox
 256 The CPU-to-SPU communication mailbox.
 257 It is write-only and can be written in units of four bytes.
 258 If the mailbox is full,
 259 .BR write (2)
 260 will block, and
 261 .BR poll (2)
 262 can be used to block until the mailbox is available for writing again.
 263 The possible operations on an open
 264 .I wbox
 265 file are:
 266 .RS
 267 .TP
 268 .BR write (2)
 269 If
 270 .I count
 271 is smaller than four,
 272 .BR write (2)
 273 returns \-1 and sets
 274 .I errno
 275 to
 276 .BR EINVAL .
 277 If there is no space available in the mailbox and the file
 278 descriptor has been opened with
 279 .BR O_NONBLOCK ,
 280 the return
 281 value is set to \-1 and
 282 .I errno
 283 is set to
 284 .BR EAGAIN .
 285
 286 If there is no space available in the mailbox and the file
 287 descriptor has been opened without
 288 .BR O_NONBLOCK ,
 289 the call will block until the SPU reads from its
 290 PPE (PowerPC Processing Element)
 291 mailbox channel.
 292 When data has been written successfully,
 293 the system call returns four as its function result.
 294 .TP
 295 .BR poll (2)
 296 A poll on the
 297 .I wbox
 298 file returns
 299 .I "(POLLOUT | POLLWRNORM)"
 300 whenever space is available for writing.
 301 .RE
 302 .TP
 303 .IR /mbox_stat ", " /ibox_stat ", " /wbox_stat
 304 These are read-only files that contain the length of the current
 305 queue of each mailbox, i.e., how many words can be read from
 306 .IR mbox " or " ibox
 307 or how many words can be written to
 308 .I wbox
 309 without blocking.
 310 The files can be read only in four-byte units and return
 311 a big-endian binary integer number.
 312 The only possible operation on an open
 313 .I *box_stat
 314 file is:
 315 .RS
 316 .TP
 317 .BR read (2)
 318 If
 319 .I count
 320 is smaller than four,
 321 .BR read (2)
 322 returns \-1 and sets
 323 .I errno
 324 to
 325 .BR EINVAL .
 326 Otherwise, a four-byte value is placed in the data buffer.
 327 This value is the number of elements that can be read from (for
 328 .IR mbox_stat
 329 and
 330 .IR ibox_stat )
 331 or written to (for
 332 .IR wbox_stat )
 333 the respective mailbox without blocking or returning an
 334 .BR EAGAIN
 335 error.
 336 .RE
 337 .TP
 338 .IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \
 339 /event_mask ", " /event_status ", " /srr0 ", " /lslr
 340 Internal registers of the SPU.
 341 These files contain an ASCII string
 342 representing the hex value of the specified register.
 343 Reads and writes on these
 344 files (except for
 345 .IR npc ,
 346 see below) require that the SPU context be scheduled out,
 347 so frequent access to
 348 these files is not recommended for normal program operation.
 349 .IP
 350 The contents of these files are:
 351 .RS
 352 .TP 16
 353 .I npc
 354 Next Program Counter \- only valid when the SPU is in a stopped state.
 355 .TP
 356 .I decr
 357 SPU Decrementer
 358 .TP
 359 .I decr_status
 360 Decrementer Status
 361 .TP
 362 .I spu_tag_mask
 363 MFC tag mask for SPU DMA
 364 .TP
 365 .I event_mask
 366 Event mask for SPU interrupts
 367 .TP
 368 .I event_status
 369 Number of SPU events pending (read-only)
 370 .TP
 371 .I srr0
 372 Interrupt Return address register
 373 .TP
 374 .I lslr
 375 Local Store Limit Register
 376 .RE
 377 .IP
 378 The possible operations on these files are:
 379 .RS
 380 .TP
 381 .BR read (2)
 382 Reads the current register value.
 383 If the register value is larger than the buffer passed to the
 384 .BR read (2)
 385 system call, subsequent reads will continue reading from the same
 386 buffer, until the end of the buffer is reached.
 387
 388 When a complete string has been read, all subsequent read operations
 389 will return zero bytes and a new file descriptor needs to be opened
 390 to read a new value.
 391 .TP
 392 .BR write (2)
 393 A
 394 .BR write (2)
 395 operation on the file sets the register to the
 396 value given in the string.
 397 The string is parsed from the beginning
 398 until the first nonnumeric character or the end of the buffer.
 399 Subsequent writes to the same file descriptor overwrite the
 400 previous setting.
 401
 402 Except for the
 403 .I npc
 404 file, these files are not present on contexts that have been created with
 405 the
 406 .B SPU_CREATE_NOSCHED
 407 flag.
 408 .RE
 409 .TP
 410 .IR /fpcr
 411 This file provides access to the Floating Point Status and
 412 Control Register (fcpr) as a binary, four-byte file.
 413 The operations on the
 414 .I fpcr
 415 file are:
 416 .RS
 417 .TP
 418 .BR read (2)
 419 If
 420 .I count
 421 is smaller than four,
 422 .BR read (2)
 423 returns \-1 and sets
 424 .I errno
 425 to
 426 .BR EINVAL .
 427 Otherwise, a four-byte value is placed in the data buffer;
 428 this is the current value of the
 429 .I fpcr
 430 register.
 431 .TP
 432 .BR write (2)
 433 If
 434 .I count
 435 is smaller than four,
 436 .BR write (2)
 437 returns \-1 and sets
 438 .I errno
 439 to
 440 .BR EINVAL .
 441 Otherwise, a four-byte value is copied from the data buffer,
 442 updating the value of the
 443 .I fpcr
 444 register.
 445 .RE
 446 .TP
 447 .IR /signal1 ", " /signal2
 448 The files provide access to the two signal notification channels
 449 of an SPU.
 450 These are read-write files that operate on four-byte words.
 451 Writing to one of these files triggers an interrupt on the SPU.
 452 The value written to the signal files can
 453 be read from the SPU through a channel read or from
 454 host user space through the file.
 455 After the value has been read by the SPU, it is reset to zero.
 456 The possible operations on an open
 457 .I signal1
 458 or
 459 .I signal2
 460 file are:
 461 .RS
 462 .TP
 463 .BR read (2)
 464 If
 465 .I count
 466 is smaller than four,
 467 .BR read (2)
 468 returns \-1 and sets
 469 .I errno
 470 to
 471 .BR EINVAL .
 472 Otherwise, a four-byte value is placed in the data buffer;
 473 this is the current value of the specified signal notification
 474 register.
 475 .TP
 476 .BR write (2)
 477 If
 478 .I count
 479 is smaller than four,
 480 .BR write (2)
 481 returns \-1 and sets
 482 .I errno
 483 to
 484 .BR EINVAL .
 485 Otherwise, a four-byte value is copied from the data buffer,
 486 updating the value of the specified signal notification
 487 register.
 488 The signal notification register will either be replaced with
 489 the input data or will be updated to the bitwise OR operation
 490 of the old value and the input data, depending on the contents
 491 of the
 492 .IR signal1_type
 493 or
 494 .IR signal2_type
 495 files respectively.
 496 .RE
 497 .TP
 498 .IR /signal1_type ", " /signal2_type
 499 These two files change the behavior of the
 500 .IR signal1
 501 and
 502 .IR signal2
 503 notification files.
 504 They contain a numeric ASCII string which is read
 505 as either "1" or "0".
 506 In mode 0 (overwrite), the hardware replaces the contents
 507 of the signal channel with the data that is written to it.
 508 In mode 1 (logical OR), the hardware accumulates the bits
 509 that are subsequently written to it.
 510 The possible operations on an open
 511 .I signal1_type
 512 or
 513 .I signal2_type
 514 file are:
 515 .RS
 516 .TP
 517 .BR read (2)
 518 When the count supplied to the
 519 .BR read (2)
 520 call is shorter than the required length for the digit (plus a newline
 521 character), subsequent reads from the same file descriptor will
 522 complete the string.
 523 When a complete string has been read, all subsequent read operations
 524 will return zero bytes and a new file descriptor needs to be opened
 525 to read the value again.
 526 .TP
 527 .BR write (2)
 528 A
 529 .BR write (2)
 530 operation on the file sets the register to the
 531 value given in the string.
 532 The string is parsed from the beginning
 533 until the first nonnumeric character or the end of the buffer.
 534 Subsequent writes to the same file descriptor overwrite the
 535 previous setting.
 536 .RE
 537 .TP
 538 .IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info
 539 Read-only files that contain the saved state of the SPU mailboxes and
 540 DMA queues.
 541 This allows the SPU status to be inspected, mainly for debugging.
 542 The
 543 .I mbox_info
 544 and
 545 .I ibox_info
 546 files each contain the four-byte mailbox message that has been written
 547 by the SPU.
 548 If no message has been written to these mailboxes, then
 549 contents of these files is undefined.
 550 The
 551 .IR mbox_stat ,
 552 .I ibox_stat
 553 and
 554 .I wbox_stat
 555 files contain the available message count.
 556
 557 The
 558 .I wbox_info
 559 file contains an array of four-byte mailbox messages, which have been
 560 sent to the SPU.
 561 With current CBEA machines, the array is four items in
 562 length, so up to 4 * 4 = 16 bytes can be read from this file.
 563 If any mailbox queue entry is empty,
 564 then the bytes read at the corresponding location are undefined.
 565
 566 The
 567 .I dma_info
 568 file contains the contents of the SPU MFC DMA queue, represented as the
 569 following structure:
 570
 571 .in +4n
 572 .nf
 573 struct spu_dma_info {
 574     uint64_t         dma_info_type;
 575     uint64_t         dma_info_mask;
 576     uint64_t         dma_info_status;
 577     uint64_t         dma_info_stall_and_notify;
 578     uint64_t         dma_info_atomic_command_status;
 579     struct mfc_cq_sr dma_info_command_data[16];
 580 };
 581 .fi
 582 .in
 583
 584 The last member of this data structure is the actual DMA queue,
 585 containing 16 entries.
 586 The
 587 .I mfc_cq_sr
 588 structure is defined as:
 589
 590 .in +4n
 591 .nf
 592 struct mfc_cq_sr {
 593     uint64_t mfc_cq_data0_RW;
 594     uint64_t mfc_cq_data1_RW;
 595     uint64_t mfc_cq_data2_RW;
 596     uint64_t mfc_cq_data3_RW;
 597 };
 598 .fi
 599 .in
 600
 601 The
 602 .I proxydma_info
 603 file contains similar information, but describes the proxy DMA queue
 604 (i.e., DMAs initiated by entities outside the SPU) instead.
 605 The file is in the following format:
 606
 607 .in +4n
 608 .nf
 609 struct spu_proxydma_info {
 610     uint64_t         proxydma_info_type;
 611     uint64_t         proxydma_info_mask;
 612     uint64_t         proxydma_info_status;
 613     struct mfc_cq_sr proxydma_info_command_data[8];
 614 };
 615 .fi
 616 .in
 617
 618 Accessing these files requires that the SPU context is scheduled out -
 619 frequent use can be inefficient.
 620 These files should not be used for normal program operation.
 621
 622 These files are not present on contexts that have been created with the
 623 .B SPU_CREATE_NOSCHED
 624 flag.
 625 .TP
 626 .IR /cntl
 627 This file provides access to the SPU Run Control and SPU status
 628 registers, as an ASCII string.
 629 The following operations are supported:
 630 .RS
 631 .TP
 632 .BR read (2)
 633 Reads from the
 634 .I cntl
 635 file will return an ASCII string with the hex
 636 value of the SPU Status register.
 637 .TP
 638 .BR write (2)
 639 Writes to the
 640 .I cntl
 641 file will set the context's SPU Run Control register.
 642 .RE
 643 .TP
 644 .I /mfc
 645 Provides access to the Memory Flow Controller of the SPU.
 646 Reading from the file returns the contents of the
 647 SPU's MFC Tag Status register, and
 648 writing to the file initiates a DMA from the MFC.
 649 The following operations are supported:
 650 .RS
 651 .TP
 652 .BR write (2)
 653 Writes to this file need to be in the format of a MFC DMA command,
 654 defined as follows:
 655
 656 .in +4n
 657 .nf
 658 struct mfc_dma_command {
 659     int32_t  pad;    /* reserved */
 660     uint32_t lsa;    /* local storage address */
 661     uint64_t ea;     /* effective address */
 662     uint16_t size;   /* transfer size */
 663     uint16_t tag;    /* command tag */
 664     uint16_t class;  /* class ID */
 665     uint16_t cmd;    /* command opcode */
 666 };
 667 .fi
 668 .in
 669
 670 Writes are required to be exactly
 671 .I sizeof(struct mfc_dma_command)
 672 bytes in size.
 673 The command will be sent to the SPU's MFC proxy queue, and the
 674 tag stored in the kernel (see below).
 675 .TP
 676 .BR read (2)
 677 Reads the contents of the tag status register.
 678 If the file is opened in blocking mode (i.e., without
 679 .BR O_NONBLOCK ),
 680 then the read will block until a
 681 DMA tag (as performed by a previous write) is complete.
 682 In nonblocking mode,
 683 the MFC tag status register will be returned without waiting.
 684 .TP
 685 .BR poll (2)
 686 Calling
 687 .BR poll (2)
 688 on the
 689 .I mfc
 690 file will block until a new DMA can be
 691 started (by checking for
 692 .BR POLLOUT )
 693 or until a previously started DMA
 694 (by checking for
 695 .BR POLLIN )
 696 has been completed.
 697
 698 .I /mss
 699 Provides access to the MFC MultiSource Synchronization (MSS) facility.
 700 By
 701 .BR mmap (2)-ing
 702 this file, processes can access the MSS area of the SPU.
 703
 704 The following operations are supported:
 705 .TP
 706 .BR mmap (2)
 707 Mapping
 708 .B mss
 709 into the process address space gives access to the SPU MSS area
 710 within the process address space.
 711 Only
 712 .B MAP_SHARED
 713 mappings are allowed.
 714 .RE
 715 .TP
 716 .I /psmap
 717 Provides access to the whole problem-state mapping of the SPU.
 718 Applications can use this area to interface to the SPU, rather than
 719 writing to individual register files in
 720 .BR spufs .
 721
 722 The following operations are supported:
 723 .RS
 724 .TP
 725 .BR mmap (2)
 726 Mapping
 727 .B psmap
 728 gives a process a direct map of the SPU problem state area.
 729 Only
 730 .B MAP_SHARED
 731 mappings are supported.
 732 .RE
 733 .TP
 734 .I /phys-id
 735 Read-only file containing the physical SPU number that the SPU context
 736 is running on.
 737 When the context is not running, this file contains the
 738 string "\-1".
 739
 740 The physical SPU number is given by an ASCII hex string.
 741 .TP
 742 .I /object-id
 743 Allows applications to store (or retrieve) a single 64-bit ID into the
 744 context.
 745 This ID is later used by profiling tools to uniquely identify
 746 the context.
 747 .RS
 748 .TP
 749 .BR write (2)
 750 By writing an ASCII hex value into this file, applications can set the
 751 object ID of the SPU context.
 752 Any previous value of the object ID is overwritten.
 753 .TP
 754 .BR read (2)
 755 Reading this file gives an ASCII hex string representing the object ID
 756 for this SPU context.
 757 .RE
 758 .SH EXAMPLE
 759 .TP
 760 .IR /etc/fstab "  entry"
 761 none    /spu    spufs   gid=spu         0       0
 762 .\" .SH AUTHORS
 763 .\" Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
 764 .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 765 .SH SEE ALSO
 766 .BR close (2),
 767 .BR spu_create (2),
 768 .BR spu_run (2),
 769 .BR capabilities (7),
 770 .I The Cell Broadband Engine Architecture (CBEA) specification