diff options
Diffstat (limited to 'man7/spufs.7')
| -rw-r--r-- | man7/spufs.7 | 804 |
1 files changed, 0 insertions, 804 deletions
diff --git a/man7/spufs.7 b/man7/spufs.7 deleted file mode 100644 index 3e8c2ed..0000000 --- a/man7/spufs.7 +++ /dev/null @@ -1,804 +0,0 @@ -.\" Copyright (c) International Business Machines Corp., 2006 -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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). -.P -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. -.P -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. -.P -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 . -.P -All files support the -.BR chmod (2)/\c -.BR fchmod (2) -and -.BR chown (2)/\c -.BR 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). -.P -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. -.P -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) -.TQ -.BR pread (2) -.TQ -.BR write (2) -.TQ -.BR pwrite (2) -.TQ -.BR 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 -.I /mbox_stat -.TQ -.I /ibox_stat -.TQ -.I /wbox_stat -These are read-only files that contain the length of the current -queue of each mailbox\[em]that 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 -.I mbox_stat -and -.IR ibox_stat ) -or written to (for -.IR wbox_stat ) -the respective mailbox without blocking or returning an -.B EAGAIN -error. -.RE -.TP -.I /npc -.TQ -.I /decr -.TQ -.I /decr_status -.TQ -.I /spu_tag_mask -.TQ -.I /event_mask -.TQ -.I /event_status -.TQ -.I /srr0 -.TQ -.I /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 -.I /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 -.I /signal1 -.TQ -.I /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 -.I signal1_type -or -.I signal2_type -files respectively. -.RE -.TP -.I /signal1_type -.TQ -.I /signal2_type -These two files change the behavior of the -.I signal1 -and -.I 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 -.I /mbox_info -.TQ -.I /ibox_info -.TQ -.I /wbox_info -.TQ -.I /dma_into -.TQ -.I /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 , -.IR 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 -.I /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 EXAMPLES -To automatically -.BR mount (8) -the SPU filesystem when booting, at the location -.I /spu -chosen by the user, put this line into the -.BR fstab (5) -configuration file: -.EX -none /spu spufs gid=spu 0 0 -.EE -.\" .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) -.P -.I The Cell Broadband Engine Architecture (CBEA) specification |