Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 804 insertions, 0 deletions

diff --git a/man/man7/spufs.7 b/man/man7/spufs.7
new file mode 100644
index 0000000..7b1ca6a
--- /dev/null
+++ b/man/man7/spufs.7
@@ -0,0 +1,804 @@
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.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