man7/spufs.7

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