| .\" Copyright (c) International Business Machines Corp., 2006 |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
| .\" This program is free software; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" This program is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See |
| .\" the GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" HISTORY: |
| .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>, |
| .\" Mark Nutter <mnutter@us.ibm.com> and |
| .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com> |
| .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com> |
| .\" 2007-07-10, quite a lot of polishing by mtk |
| .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> |
| .\" |
| .TH SPUFS 7 2017-09-15 Linux "Linux Programmer's Manual" |
| .SH NAME |
| spufs \- SPU filesystem |
| .SH DESCRIPTION |
| The SPU filesystem is used on PowerPC machines that implement the |
| Cell Broadband Engine Architecture in order to access Synergistic |
| Processor Units (SPUs). |
| .PP |
| The filesystem provides a name space similar to POSIX shared |
| memory or message queues. |
| Users that have write permissions |
| on the filesystem can use |
| .BR spu_create (2) |
| to establish SPU contexts under the |
| .B spufs |
| root directory. |
| .PP |
| Every SPU context is represented by a directory containing |
| a predefined set of files. |
| These files can be |
| used for manipulating the state of the logical SPU. |
| Users can change permissions on the files, but can't |
| add or remove files. |
| .SS Mount options |
| .TP |
| .B uid=<uid> |
| Set the user owning the mount point; the default is 0 (root). |
| .TP |
| .B gid=<gid> |
| Set the group owning the mount point; the default is 0 (root). |
| .TP |
| .B mode=<mode> |
| Set the mode of the top-level directory in |
| .BR spufs , |
| as an octal mode string. |
| The default is 0775. |
| .SS Files |
| The files in |
| .B spufs |
| mostly follow the standard behavior for regular system calls like |
| .BR read (2) |
| or |
| .BR write (2), |
| but often support only a subset of the operations |
| supported on regular filesystems. |
| This list details the supported |
| operations and the deviations from the standard behavior described |
| in the respective man pages. |
| .PP |
| All files that support the |
| .BR read (2) |
| operation also support |
| .BR readv (2) |
| and all files that support the |
| .BR write (2) |
| operation also support |
| .BR writev (2). |
| All files support the |
| .BR access (2) |
| and |
| .BR stat (2) |
| family of operations, but for the latter call, |
| the only fields of the returned |
| .I stat |
| structure that contain reliable information are |
| .IR st_mode , |
| .IR st_nlink , |
| .IR st_uid , |
| and |
| .IR st_gid . |
| .PP |
| All files support the |
| .BR chmod (2)/ fchmod (2) |
| and |
| .BR chown (2)/ fchown (2) |
| operations, but will not be able to grant permissions that contradict |
| the possible operations (e.g., read access on the |
| .I wbox |
| file). |
| .PP |
| The current set of files is: |
| .TP |
| .I /capabilities |
| Contains a comma-delimited string representing the capabilities of this |
| SPU context. |
| Possible capabilities are: |
| .RS |
| .TP |
| .B sched |
| This context may be scheduled. |
| .TP |
| .B step |
| This context can be run in single-step mode, for debugging. |
| .PP |
| New capabilities flags may be added in the future. |
| .RE |
| .TP |
| .I /mem |
| the contents of the local storage memory of the SPU. |
| This can be accessed like a regular shared memory |
| file and contains both code and data in the address |
| space of the SPU. |
| The possible operations on an open |
| .I mem |
| file are: |
| .RS |
| .TP |
| .BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2) |
| These operate as usual, with the exception that |
| .BR lseek (2), |
| .BR write (2), |
| and |
| .BR pwrite (2) |
| are not supported beyond the end of the file. |
| The file size |
| is the size of the local storage of the SPU, |
| which is normally 256 kilobytes. |
| .TP |
| .BR mmap (2) |
| Mapping |
| .I mem |
| into the process address space provides access to the SPU local |
| storage within the process address space. |
| Only |
| .B MAP_SHARED |
| mappings are allowed. |
| .RE |
| .TP |
| .I /regs |
| Contains the saved general-purpose registers of the SPU context. |
| This file contains the 128-bit values of each register, |
| from register 0 to register 127, in order. |
| This allows the general-purpose registers to be |
| inspected for debugging. |
| .IP |
| Reading to or writing from this file requires that the context is |
| scheduled out, so use of this file is not recommended in normal |
| program operation. |
| .IP |
| The |
| .I regs |
| file is not present on contexts that have been created with the |
| .B SPU_CREATE_NOSCHED |
| flag. |
| .TP |
| .I /mbox |
| The first SPU-to-CPU communication mailbox. |
| This file is read-only and can be read in units of 4 bytes. |
| The file can be used only in nonblocking mode \- even |
| .BR poll (2) |
| cannot be used to block on this file. |
| The only possible operation on an open |
| .I mbox |
| file is: |
| .RS |
| .TP |
| .BR read (2) |
| If |
| .I count |
| is smaller than four, |
| .BR read (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| If there is no data available in the mailbox (i.e., the SPU has not |
| sent a mailbox message), the return value is set to \-1 and |
| .I errno |
| is set to |
| .BR EAGAIN . |
| When data |
| has been read successfully, four bytes are placed in |
| the data buffer and the value four is returned. |
| .RE |
| .TP |
| .I /ibox |
| The second SPU-to-CPU communication mailbox. |
| This file is similar to the first mailbox file, but can be read |
| in blocking I/O mode, thus calling |
| .BR read (2) |
| on an open |
| .I ibox |
| file will block until the SPU has written data to its interrupt mailbox |
| channel (unless the file has been opened with |
| .BR O_NONBLOCK , |
| see below). |
| Also, |
| .BR poll (2) |
| and similar system calls can be used to monitor for the presence |
| of mailbox data. |
| .IP |
| The possible operations on an open |
| .I ibox |
| file are: |
| .RS |
| .TP |
| .BR read (2) |
| If |
| .I count |
| is smaller than four, |
| .BR read (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| If there is no data available in the mailbox and the file |
| descriptor has been opened with |
| .BR O_NONBLOCK , |
| the return value is set to \-1 and |
| .I errno |
| is set to |
| .BR EAGAIN . |
| .IP |
| If there is no data available in the mailbox and the file |
| descriptor has been opened without |
| .BR O_NONBLOCK , |
| the call will |
| block until the SPU writes to its interrupt mailbox channel. |
| When data has been read successfully, four bytes are placed in |
| the data buffer and the value four is returned. |
| .TP |
| .BR poll (2) |
| Poll on the |
| .I ibox |
| file returns |
| .I "(POLLIN | POLLRDNORM)" |
| whenever data is available for reading. |
| .RE |
| .TP |
| .I /wbox |
| The CPU-to-SPU communication mailbox. |
| It is write-only and can be written in units of four bytes. |
| If the mailbox is full, |
| .BR write (2) |
| will block, and |
| .BR poll (2) |
| can be used to block until the mailbox is available for writing again. |
| The possible operations on an open |
| .I wbox |
| file are: |
| .RS |
| .TP |
| .BR write (2) |
| If |
| .I count |
| is smaller than four, |
| .BR write (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| If there is no space available in the mailbox and the file |
| descriptor has been opened with |
| .BR O_NONBLOCK , |
| the return |
| value is set to \-1 and |
| .I errno |
| is set to |
| .BR EAGAIN . |
| .IP |
| If there is no space available in the mailbox and the file |
| descriptor has been opened without |
| .BR O_NONBLOCK , |
| the call will block until the SPU reads from its |
| PPE (PowerPC Processing Element) |
| mailbox channel. |
| When data has been written successfully, |
| the system call returns four as its function result. |
| .TP |
| .BR poll (2) |
| A poll on the |
| .I wbox |
| file returns |
| .I "(POLLOUT | POLLWRNORM)" |
| whenever space is available for writing. |
| .RE |
| .TP |
| .IR /mbox_stat ", " /ibox_stat ", " /wbox_stat |
| These are read-only files that contain the length of the current |
| queue of each mailbox\(emthat is, how many words can be read from |
| .IR mbox " or " ibox |
| or how many words can be written to |
| .I wbox |
| without blocking. |
| The files can be read only in four-byte units and return |
| a big-endian binary integer number. |
| The only possible operation on an open |
| .I *box_stat |
| file is: |
| .RS |
| .TP |
| .BR read (2) |
| If |
| .I count |
| is smaller than four, |
| .BR read (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| Otherwise, a four-byte value is placed in the data buffer. |
| This value is the number of elements that can be read from (for |
| .IR mbox_stat |
| and |
| .IR ibox_stat ) |
| or written to (for |
| .IR wbox_stat ) |
| the respective mailbox without blocking or returning an |
| .BR EAGAIN |
| error. |
| .RE |
| .TP |
| .IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \ |
| /event_mask ", " /event_status ", " /srr0 ", " /lslr |
| Internal registers of the SPU. |
| These files contain an ASCII string |
| representing the hex value of the specified register. |
| Reads and writes on these |
| files (except for |
| .IR npc , |
| see below) require that the SPU context be scheduled out, |
| so frequent access to |
| these files is not recommended for normal program operation. |
| .IP |
| The contents of these files are: |
| .RS |
| .TP 16 |
| .I npc |
| Next Program Counter \- valid only when the SPU is in a stopped state. |
| .TP |
| .I decr |
| SPU Decrementer |
| .TP |
| .I decr_status |
| Decrementer Status |
| .TP |
| .I spu_tag_mask |
| MFC tag mask for SPU DMA |
| .TP |
| .I event_mask |
| Event mask for SPU interrupts |
| .TP |
| .I event_status |
| Number of SPU events pending (read-only) |
| .TP |
| .I srr0 |
| Interrupt Return address register |
| .TP |
| .I lslr |
| Local Store Limit Register |
| .RE |
| .IP |
| The possible operations on these files are: |
| .RS |
| .TP |
| .BR read (2) |
| Reads the current register value. |
| If the register value is larger than the buffer passed to the |
| .BR read (2) |
| system call, subsequent reads will continue reading from the same |
| buffer, until the end of the buffer is reached. |
| .IP |
| When a complete string has been read, all subsequent read operations |
| will return zero bytes and a new file descriptor needs to be opened |
| to read a new value. |
| .TP |
| .BR write (2) |
| A |
| .BR write (2) |
| operation on the file sets the register to the |
| value given in the string. |
| The string is parsed from the beginning |
| until the first nonnumeric character or the end of the buffer. |
| Subsequent writes to the same file descriptor overwrite the |
| previous setting. |
| .IP |
| Except for the |
| .I npc |
| file, these files are not present on contexts that have been created with |
| the |
| .B SPU_CREATE_NOSCHED |
| flag. |
| .RE |
| .TP |
| .IR /fpcr |
| This file provides access to the Floating Point Status and |
| Control Register (fcpr) as a binary, four-byte file. |
| The operations on the |
| .I fpcr |
| file are: |
| .RS |
| .TP |
| .BR read (2) |
| If |
| .I count |
| is smaller than four, |
| .BR read (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| Otherwise, a four-byte value is placed in the data buffer; |
| this is the current value of the |
| .I fpcr |
| register. |
| .TP |
| .BR write (2) |
| If |
| .I count |
| is smaller than four, |
| .BR write (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| Otherwise, a four-byte value is copied from the data buffer, |
| updating the value of the |
| .I fpcr |
| register. |
| .RE |
| .TP |
| .IR /signal1 ", " /signal2 |
| The files provide access to the two signal notification channels |
| of an SPU. |
| These are read-write files that operate on four-byte words. |
| Writing to one of these files triggers an interrupt on the SPU. |
| The value written to the signal files can |
| be read from the SPU through a channel read or from |
| host user space through the file. |
| After the value has been read by the SPU, it is reset to zero. |
| The possible operations on an open |
| .I signal1 |
| or |
| .I signal2 |
| file are: |
| .RS |
| .TP |
| .BR read (2) |
| If |
| .I count |
| is smaller than four, |
| .BR read (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| Otherwise, a four-byte value is placed in the data buffer; |
| this is the current value of the specified signal notification |
| register. |
| .TP |
| .BR write (2) |
| If |
| .I count |
| is smaller than four, |
| .BR write (2) |
| returns \-1 and sets |
| .I errno |
| to |
| .BR EINVAL . |
| Otherwise, a four-byte value is copied from the data buffer, |
| updating the value of the specified signal notification |
| register. |
| The signal notification register will either be replaced with |
| the input data or will be updated to the bitwise OR operation |
| of the old value and the input data, depending on the contents |
| of the |
| .IR signal1_type |
| or |
| .IR signal2_type |
| files respectively. |
| .RE |
| .TP |
| .IR /signal1_type ", " /signal2_type |
| These two files change the behavior of the |
| .IR signal1 |
| and |
| .IR signal2 |
| notification files. |
| They contain a numeric ASCII string which is read |
| as either "1" or "0". |
| In mode 0 (overwrite), the hardware replaces the contents |
| of the signal channel with the data that is written to it. |
| In mode 1 (logical OR), the hardware accumulates the bits |
| that are subsequently written to it. |
| The possible operations on an open |
| .I signal1_type |
| or |
| .I signal2_type |
| file are: |
| .RS |
| .TP |
| .BR read (2) |
| When the count supplied to the |
| .BR read (2) |
| call is shorter than the required length for the digit (plus a newline |
| character), subsequent reads from the same file descriptor will |
| complete the string. |
| When a complete string has been read, all subsequent read operations |
| will return zero bytes and a new file descriptor needs to be opened |
| to read the value again. |
| .TP |
| .BR write (2) |
| A |
| .BR write (2) |
| operation on the file sets the register to the |
| value given in the string. |
| The string is parsed from the beginning |
| until the first nonnumeric character or the end of the buffer. |
| Subsequent writes to the same file descriptor overwrite the |
| previous setting. |
| .RE |
| .TP |
| .IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info |
| Read-only files that contain the saved state of the SPU mailboxes and |
| DMA queues. |
| This allows the SPU status to be inspected, mainly for debugging. |
| The |
| .I mbox_info |
| and |
| .I ibox_info |
| files each contain the four-byte mailbox message that has been written |
| by the SPU. |
| If no message has been written to these mailboxes, then |
| contents of these files is undefined. |
| The |
| .IR mbox_stat , |
| .I ibox_stat |
| and |
| .I wbox_stat |
| files contain the available message count. |
| .IP |
| The |
| .I wbox_info |
| file contains an array of four-byte mailbox messages, which have been |
| sent to the SPU. |
| With current CBEA machines, the array is four items in |
| length, so up to 4 * 4 = 16 bytes can be read from this file. |
| If any mailbox queue entry is empty, |
| then the bytes read at the corresponding location are undefined. |
| .IP |
| The |
| .I dma_info |
| file contains the contents of the SPU MFC DMA queue, represented as the |
| following structure: |
| .IP |
| .in +4n |
| .EX |
| struct spu_dma_info { |
| uint64_t dma_info_type; |
| uint64_t dma_info_mask; |
| uint64_t dma_info_status; |
| uint64_t dma_info_stall_and_notify; |
| uint64_t dma_info_atomic_command_status; |
| struct mfc_cq_sr dma_info_command_data[16]; |
| }; |
| .EE |
| .in |
| .IP |
| The last member of this data structure is the actual DMA queue, |
| containing 16 entries. |
| The |
| .I mfc_cq_sr |
| structure is defined as: |
| .IP |
| .in +4n |
| .EX |
| struct mfc_cq_sr { |
| uint64_t mfc_cq_data0_RW; |
| uint64_t mfc_cq_data1_RW; |
| uint64_t mfc_cq_data2_RW; |
| uint64_t mfc_cq_data3_RW; |
| }; |
| .EE |
| .in |
| .IP |
| The |
| .I proxydma_info |
| file contains similar information, but describes the proxy DMA queue |
| (i.e., DMAs initiated by entities outside the SPU) instead. |
| The file is in the following format: |
| .IP |
| .in +4n |
| .EX |
| struct spu_proxydma_info { |
| uint64_t proxydma_info_type; |
| uint64_t proxydma_info_mask; |
| uint64_t proxydma_info_status; |
| struct mfc_cq_sr proxydma_info_command_data[8]; |
| }; |
| .EE |
| .in |
| .IP |
| Accessing these files requires that the SPU context is scheduled out - |
| frequent use can be inefficient. |
| These files should not be used for normal program operation. |
| .IP |
| These files are not present on contexts that have been created with the |
| .B SPU_CREATE_NOSCHED |
| flag. |
| .TP |
| .IR /cntl |
| This file provides access to the SPU Run Control and SPU status |
| registers, as an ASCII string. |
| The following operations are supported: |
| .RS |
| .TP |
| .BR read (2) |
| Reads from the |
| .I cntl |
| file will return an ASCII string with the hex |
| value of the SPU Status register. |
| .TP |
| .BR write (2) |
| Writes to the |
| .I cntl |
| file will set the context's SPU Run Control register. |
| .RE |
| .TP |
| .I /mfc |
| Provides access to the Memory Flow Controller of the SPU. |
| Reading from the file returns the contents of the |
| SPU's MFC Tag Status register, and |
| writing to the file initiates a DMA from the MFC. |
| The following operations are supported: |
| .RS |
| .TP |
| .BR write (2) |
| Writes to this file need to be in the format of a MFC DMA command, |
| defined as follows: |
| .IP |
| .in +4n |
| .EX |
| struct mfc_dma_command { |
| int32_t pad; /* reserved */ |
| uint32_t lsa; /* local storage address */ |
| uint64_t ea; /* effective address */ |
| uint16_t size; /* transfer size */ |
| uint16_t tag; /* command tag */ |
| uint16_t class; /* class ID */ |
| uint16_t cmd; /* command opcode */ |
| }; |
| .EE |
| .in |
| .IP |
| Writes are required to be exactly |
| .I sizeof(struct mfc_dma_command) |
| bytes in size. |
| The command will be sent to the SPU's MFC proxy queue, and the |
| tag stored in the kernel (see below). |
| .TP |
| .BR read (2) |
| Reads the contents of the tag status register. |
| If the file is opened in blocking mode (i.e., without |
| .BR O_NONBLOCK ), |
| then the read will block until a |
| DMA tag (as performed by a previous write) is complete. |
| In nonblocking mode, |
| the MFC tag status register will be returned without waiting. |
| .TP |
| .BR poll (2) |
| Calling |
| .BR poll (2) |
| on the |
| .I mfc |
| file will block until a new DMA can be |
| started (by checking for |
| .BR POLLOUT ) |
| or until a previously started DMA |
| (by checking for |
| .BR POLLIN ) |
| has been completed. |
| .IP |
| .I /mss |
| Provides access to the MFC MultiSource Synchronization (MSS) facility. |
| By |
| .BR mmap (2)-ing |
| this file, processes can access the MSS area of the SPU. |
| .IP |
| The following operations are supported: |
| .TP |
| .BR mmap (2) |
| Mapping |
| .B mss |
| into the process address space gives access to the SPU MSS area |
| within the process address space. |
| Only |
| .B MAP_SHARED |
| mappings are allowed. |
| .RE |
| .TP |
| .I /psmap |
| Provides access to the whole problem-state mapping of the SPU. |
| Applications can use this area to interface to the SPU, rather than |
| writing to individual register files in |
| .BR spufs . |
| .IP |
| The following operations are supported: |
| .RS |
| .TP |
| .BR mmap (2) |
| Mapping |
| .B psmap |
| gives a process a direct map of the SPU problem state area. |
| Only |
| .B MAP_SHARED |
| mappings are supported. |
| .RE |
| .TP |
| .I /phys-id |
| Read-only file containing the physical SPU number that the SPU context |
| is running on. |
| When the context is not running, this file contains the |
| string "\-1". |
| .IP |
| The physical SPU number is given by an ASCII hex string. |
| .TP |
| .I /object-id |
| Allows applications to store (or retrieve) a single 64-bit ID into the |
| context. |
| This ID is later used by profiling tools to uniquely identify |
| the context. |
| .RS |
| .TP |
| .BR write (2) |
| By writing an ASCII hex value into this file, applications can set the |
| object ID of the SPU context. |
| Any previous value of the object ID is overwritten. |
| .TP |
| .BR read (2) |
| Reading this file gives an ASCII hex string representing the object ID |
| for this SPU context. |
| .RE |
| .SH EXAMPLE |
| .TP |
| .IR /etc/fstab " entry" |
| none /spu spufs gid=spu 0 0 |
| .\" .SH AUTHORS |
| .\" Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>, |
| .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org> |
| .SH SEE ALSO |
| .BR close (2), |
| .BR spu_create (2), |
| .BR spu_run (2), |
| .BR capabilities (7) |
| .PP |
| .I The Cell Broadband Engine Architecture (CBEA) specification |