From 299cd2747c61009f32943217c79f3c89728eb2ac Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 27 Apr 2020 23:17:15 +0200 Subject: docs: filesystems: convert spufs/spufs.txt to ReST This file is at groff output format. Manually convert it to ReST format, trying to preserve a similar output after parsed. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/9ca05fad12390931bc7da0fa2502d1a450a4b87f.1588021877.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/filesystems/spufs/index.rst | 1 + Documentation/filesystems/spufs/spufs.rst | 273 +++++++++++++++++++++++++++++ Documentation/filesystems/spufs/spufs.txt | 276 ------------------------------ 3 files changed, 274 insertions(+), 276 deletions(-) create mode 100644 Documentation/filesystems/spufs/spufs.rst delete mode 100644 Documentation/filesystems/spufs/spufs.txt (limited to 'Documentation/filesystems/spufs') diff --git a/Documentation/filesystems/spufs/index.rst b/Documentation/filesystems/spufs/index.rst index 39553c6ebefd..939cf59a7d9e 100644 --- a/Documentation/filesystems/spufs/index.rst +++ b/Documentation/filesystems/spufs/index.rst @@ -8,4 +8,5 @@ SPU Filesystem .. toctree:: :maxdepth: 1 + spufs spu_create diff --git a/Documentation/filesystems/spufs/spufs.rst b/Documentation/filesystems/spufs/spufs.rst new file mode 100644 index 000000000000..8a42859bb100 --- /dev/null +++ b/Documentation/filesystems/spufs/spufs.rst @@ -0,0 +1,273 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +spufs +===== + +Name +==== + + spufs - the SPU file system + + +Description +=========== + + The SPU file system is used on PowerPC machines that implement the Cell + Broadband Engine Architecture in order to access Synergistic Processor + Units (SPUs). + + The file system provides a name space similar to posix shared memory or + message queues. Users that have write permissions on the file system + can use spu_create(2) to establish SPU contexts in the spufs root. + + 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 those files, but not actu- + ally add or remove files. + + +Mount Options +============= + + uid= + set the user owning the mount point, the default is 0 (root). + + gid= + set the group owning the mount point, the default is 0 (root). + + +Files +===== + + The files in spufs mostly follow the standard behavior for regular sys- + tem calls like read(2) or write(2), but often support only a subset of + the operations supported on regular file systems. This list details the + supported operations and the deviations from the behaviour in the + respective man pages. + + All files that support the read(2) operation also support readv(2) and + all files that support the write(2) operation also support writev(2). + All files support the access(2) and stat(2) family of operations, but + only the st_mode, st_nlink, st_uid and st_gid fields of struct stat + contain reliable information. + + All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera- + tions, but will not be able to grant permissions that contradict the + possible operations, e.g. read access on the wbox file. + + The current set of files is: + + + /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 mem file are: + + read(2), pread(2), write(2), pwrite(2), lseek(2) + These operate as documented, with the exception that seek(2), + write(2) and 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 normally is 256 kilobytes. + + mmap(2) + Mapping mem into the process address space gives access to the + SPU local storage within the process address space. Only + MAP_SHARED mappings are allowed. + + + /mbox + The first SPU to CPU communication mailbox. This file is read-only and + can be read in units of 32 bits. The file can only be used in non- + blocking mode and it even poll() will not block on it. The possible + operations on an open mbox file are: + + read(2) + If a count smaller than four is requested, read returns -1 and + sets errno to EINVAL. If there is no data available in the mail + box, the return value is set to -1 and errno becomes EAGAIN. + When data has been read successfully, four bytes are placed in + the data buffer and the value four is returned. + + + /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, and the + poll family of system calls can be used to wait for it. The possible + operations on an open ibox file are: + + read(2) + If a count smaller than four is requested, read returns -1 and + sets errno to EINVAL. If there is no data available in the mail + box and the file descriptor has been opened with O_NONBLOCK, the + return value is set to -1 and errno becomes EAGAIN. + + If there is no data available in the mail box and the file + descriptor has been opened without 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. + + poll(2) + Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever + data is available for reading. + + + /wbox + The CPU to SPU communation mailbox. It is write-only and can be written + in units of 32 bits. If the mailbox is full, write() will block and + poll can be used to wait for it becoming empty again. The possible + operations on an open wbox file are: write(2) If a count smaller than + four is requested, write returns -1 and sets errno to EINVAL. If there + is no space available in the mail box and the file descriptor has been + opened with O_NONBLOCK, the return value is set to -1 and errno becomes + EAGAIN. + + If there is no space available in the mail box and the file descriptor + has been opened without O_NONBLOCK, the call will block until the SPU + reads from its PPE mailbox channel. When data has been read success- + fully, four bytes are placed in the data buffer and the value four is + returned. + + poll(2) + Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever + space is available for writing. + + + /mbox_stat, /ibox_stat, /wbox_stat + Read-only files that contain the length of the current queue, i.e. how + many words can be read from mbox or ibox or how many words can be + written to wbox without blocking. The files can be read only in 4-byte + units and return a big-endian binary integer number. The possible + operations on an open ``*box_stat`` file are: + + read(2) + If a count smaller than four is requested, read returns -1 and + sets errno to EINVAL. Otherwise, a four byte value is placed in + the data buffer, containing the number of elements that can be + read from (for mbox_stat and ibox_stat) or written to (for + wbox_stat) the respective mail box without blocking or resulting + in EAGAIN. + + + /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /srr0 + Internal registers of the SPU. The representation is an ASCII string + with the numeric value of the next instruction to be executed. These + can be used in read/write mode for debugging, but normal operation of + programs should not rely on them because access to any of them except + npc requires an SPU context save and is therefore very inefficient. + + The contents of these files are: + + =================== =================================== + npc Next Program Counter + decr SPU Decrementer + decr_status Decrementer Status + spu_tag_mask MFC tag mask for SPU DMA + event_mask Event mask for SPU interrupts + srr0 Interrupt Return address register + =================== =================================== + + + The possible operations on an open npc, decr, decr_status, + spu_tag_mask, event_mask or srr0 file are: + + read(2) + When the count supplied to the read call is shorter than the + required length for the pointer value plus a newline character, + subsequent reads from the same file descriptor will result in + completing the string, regardless of changes to the register by + a running SPU task. 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. + + write(2) + A write operation on the file results in setting the register to + the value given in the string. The string is parsed from the + beginning to the first non-numeric character or the end of the + buffer. Subsequent writes to the same file descriptor overwrite + the previous setting. + + + /fpcr + This file gives access to the Floating Point Status and Control Regis- + ter as a four byte long file. The operations on the fpcr file are: + + read(2) + If a count smaller than four is requested, read returns -1 and + sets errno to EINVAL. Otherwise, a four byte value is placed in + the data buffer, containing the current value of the fpcr regis- + ter. + + write(2) + If a count smaller than four is requested, write returns -1 and + sets errno to EINVAL. Otherwise, a four byte value is copied + from the data buffer, updating the value of the fpcr register. + + + /signal1, /signal2 + The two signal notification channels of an SPU. These are read-write + files that operate on a 32 bit word. 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 signal1 or sig- + nal2 file are: + + read(2) + If a count smaller than four is requested, read returns -1 and + sets errno to EINVAL. Otherwise, a four byte value is placed in + the data buffer, containing the current value of the specified + signal notification register. + + write(2) + If a count smaller than four is requested, write returns -1 and + sets errno to 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 or the old value and the input data, depending on the + contents of the signal1_type, or signal2_type respectively, + file. + + + /signal1_type, /signal2_type + These two files change the behavior of the signal1 and signal2 notifi- + cation files. The contain a numerical 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 subse- + quently written to it. The possible operations on an open signal1_type + or signal2_type file are: + + read(2) + When the count supplied to the read call is shorter than the + required length for the digit plus a newline character, subse- + quent reads from the same file descriptor will result in com- + pleting 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. + + write(2) + A write operation on the file results in setting the register to + the value given in the string. The string is parsed from the + beginning to the first non-numeric character or the end of the + buffer. Subsequent writes to the same file descriptor overwrite + the previous setting. + + +Examples +======== + /etc/fstab entry + none /spu spufs gid=spu 0 0 + + +Authors +======= + Arnd Bergmann , Mark Nutter , + Ulrich Weigand + +See Also +======== + capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7) diff --git a/Documentation/filesystems/spufs/spufs.txt b/Documentation/filesystems/spufs/spufs.txt deleted file mode 100644 index caf36aaae804..000000000000 --- a/Documentation/filesystems/spufs/spufs.txt +++ /dev/null @@ -1,276 +0,0 @@ -SPUFS(2) Linux Programmer's Manual SPUFS(2) - - - -NAME - spufs - the SPU file system - - -DESCRIPTION - The SPU file system is used on PowerPC machines that implement the Cell - Broadband Engine Architecture in order to access Synergistic Processor - Units (SPUs). - - The file system provides a name space similar to posix shared memory or - message queues. Users that have write permissions on the file system - can use spu_create(2) to establish SPU contexts in the spufs root. - - 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 those files, but not actu- - ally add or remove files. - - -MOUNT OPTIONS - uid= - set the user owning the mount point, the default is 0 (root). - - gid= - set the group owning the mount point, the default is 0 (root). - - -FILES - The files in spufs mostly follow the standard behavior for regular sys- - tem calls like read(2) or write(2), but often support only a subset of - the operations supported on regular file systems. This list details the - supported operations and the deviations from the behaviour in the - respective man pages. - - All files that support the read(2) operation also support readv(2) and - all files that support the write(2) operation also support writev(2). - All files support the access(2) and stat(2) family of operations, but - only the st_mode, st_nlink, st_uid and st_gid fields of struct stat - contain reliable information. - - All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera- - tions, but will not be able to grant permissions that contradict the - possible operations, e.g. read access on the wbox file. - - The current set of files is: - - - /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 mem file are: - - read(2), pread(2), write(2), pwrite(2), lseek(2) - These operate as documented, with the exception that seek(2), - write(2) and 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 normally is 256 kilobytes. - - mmap(2) - Mapping mem into the process address space gives access to the - SPU local storage within the process address space. Only - MAP_SHARED mappings are allowed. - - - /mbox - The first SPU to CPU communication mailbox. This file is read-only and - can be read in units of 32 bits. The file can only be used in non- - blocking mode and it even poll() will not block on it. The possible - operations on an open mbox file are: - - read(2) - If a count smaller than four is requested, read returns -1 and - sets errno to EINVAL. If there is no data available in the mail - box, the return value is set to -1 and errno becomes EAGAIN. - When data has been read successfully, four bytes are placed in - the data buffer and the value four is returned. - - - /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, and the - poll family of system calls can be used to wait for it. The possible - operations on an open ibox file are: - - read(2) - If a count smaller than four is requested, read returns -1 and - sets errno to EINVAL. If there is no data available in the mail - box and the file descriptor has been opened with O_NONBLOCK, the - return value is set to -1 and errno becomes EAGAIN. - - If there is no data available in the mail box and the file - descriptor has been opened without 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. - - poll(2) - Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever - data is available for reading. - - - /wbox - The CPU to SPU communation mailbox. It is write-only and can be written - in units of 32 bits. If the mailbox is full, write() will block and - poll can be used to wait for it becoming empty again. The possible - operations on an open wbox file are: write(2) If a count smaller than - four is requested, write returns -1 and sets errno to EINVAL. If there - is no space available in the mail box and the file descriptor has been - opened with O_NONBLOCK, the return value is set to -1 and errno becomes - EAGAIN. - - If there is no space available in the mail box and the file descriptor - has been opened without O_NONBLOCK, the call will block until the SPU - reads from its PPE mailbox channel. When data has been read success- - fully, four bytes are placed in the data buffer and the value four is - returned. - - poll(2) - Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever - space is available for writing. - - - /mbox_stat - /ibox_stat - /wbox_stat - Read-only files that contain the length of the current queue, i.e. how - many words can be read from mbox or ibox or how many words can be - written to wbox without blocking. The files can be read only in 4-byte - units and return a big-endian binary integer number. The possible - operations on an open *box_stat file are: - - read(2) - If a count smaller than four is requested, read returns -1 and - sets errno to EINVAL. Otherwise, a four byte value is placed in - the data buffer, containing the number of elements that can be - read from (for mbox_stat and ibox_stat) or written to (for - wbox_stat) the respective mail box without blocking or resulting - in EAGAIN. - - - /npc - /decr - /decr_status - /spu_tag_mask - /event_mask - /srr0 - Internal registers of the SPU. The representation is an ASCII string - with the numeric value of the next instruction to be executed. These - can be used in read/write mode for debugging, but normal operation of - programs should not rely on them because access to any of them except - npc requires an SPU context save and is therefore very inefficient. - - The contents of these files are: - - npc Next Program Counter - - decr SPU Decrementer - - decr_status Decrementer Status - - spu_tag_mask MFC tag mask for SPU DMA - - event_mask Event mask for SPU interrupts - - srr0 Interrupt Return address register - - - The possible operations on an open npc, decr, decr_status, - spu_tag_mask, event_mask or srr0 file are: - - read(2) - When the count supplied to the read call is shorter than the - required length for the pointer value plus a newline character, - subsequent reads from the same file descriptor will result in - completing the string, regardless of changes to the register by - a running SPU task. 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. - - write(2) - A write operation on the file results in setting the register to - the value given in the string. The string is parsed from the - beginning to the first non-numeric character or the end of the - buffer. Subsequent writes to the same file descriptor overwrite - the previous setting. - - - /fpcr - This file gives access to the Floating Point Status and Control Regis- - ter as a four byte long file. The operations on the fpcr file are: - - read(2) - If a count smaller than four is requested, read returns -1 and - sets errno to EINVAL. Otherwise, a four byte value is placed in - the data buffer, containing the current value of the fpcr regis- - ter. - - write(2) - If a count smaller than four is requested, write returns -1 and - sets errno to EINVAL. Otherwise, a four byte value is copied - from the data buffer, updating the value of the fpcr register. - - - /signal1 - /signal2 - The two signal notification channels of an SPU. These are read-write - files that operate on a 32 bit word. 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 signal1 or sig- - nal2 file are: - - read(2) - If a count smaller than four is requested, read returns -1 and - sets errno to EINVAL. Otherwise, a four byte value is placed in - the data buffer, containing the current value of the specified - signal notification register. - - write(2) - If a count smaller than four is requested, write returns -1 and - sets errno to 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 or the old value and the input data, depending on the - contents of the signal1_type, or signal2_type respectively, - file. - - - /signal1_type - /signal2_type - These two files change the behavior of the signal1 and signal2 notifi- - cation files. The contain a numerical 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 subse- - quently written to it. The possible operations on an open signal1_type - or signal2_type file are: - - read(2) - When the count supplied to the read call is shorter than the - required length for the digit plus a newline character, subse- - quent reads from the same file descriptor will result in com- - pleting 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. - - write(2) - A write operation on the file results in setting the register to - the value given in the string. The string is parsed from the - beginning to the first non-numeric character or the end of the - buffer. Subsequent writes to the same file descriptor overwrite - the previous setting. - - -EXAMPLES - /etc/fstab entry - none /spu spufs gid=spu 0 0 - - -AUTHORS - Arnd Bergmann , Mark Nutter , - Ulrich Weigand - -SEE ALSO - capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7) - - - -Linux 2005-09-28 SPUFS(2) -- cgit v1.2.3