Merging upstream version 6.8.

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

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