man7/spufs.7

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