diff options
Diffstat (limited to '')
| -rw-r--r-- | man7/spufs.7 | 767 |
1 files changed, 767 insertions, 0 deletions
diff --git a/man7/spufs.7 b/man7/spufs.7 new file mode 100644 index 0000000..fc3b424 --- /dev/null +++ b/man7/spufs.7 @@ -0,0 +1,767 @@ +.\" 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-02-05 "Linux man-pages 6.05.01" +.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)/\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). +.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\[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 +.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 +.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 +.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 +.I signal1_type +or +.I signal2_type +files respectively. +.RE +.TP +.IR /signal1_type ", " /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 +.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 , +.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) +.PP +.I The Cell Broadband Engine Architecture (CBEA) specification |