mirror of https://github.com/mkerrisk/man-pages
Many and various updates and improvements.
This commit is contained in:
Michael Kerrisk
parent
e5dba0b16c
commit
d24596d517
|
|
@ -1,19 +1,17 @@
|
|||
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
||||
.\" Copyright (c) International Business Machines Corp., 2006
|
||||
.\"
|
||||
.\" Copyright (c) International Business Machines Corp., 2006
|
||||
.\"
|
||||
.\" This program is free software; you can redistribute it and/or
|
||||
.\" This program is free software; you can redistribute it and/or
|
||||
.\" modify it under the terms of the GNU General Public License as
|
||||
.\" published by the Free Software Foundation; either version 2 of
|
||||
.\" the License, or (at your option) any later version.
|
||||
.\"
|
||||
.\" This program is distributed in the hope that it will be useful,
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
||||
.\" the GNU General Public License for more details.
|
||||
.\"
|
||||
.\" You should have received a copy of the GNU General Public License
|
||||
.\" along with this program; if not, write to the Free Software
|
||||
.\" along with this program; if not, write to the Free Software
|
||||
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||
.\" MA 02111-1307 USA
|
||||
.\"
|
||||
|
|
@ -21,8 +19,9 @@
|
|||
.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
|
||||
.\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
|
||||
.\" 2007-07-10, some polishing by mtk
|
||||
.\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
|
||||
.\"
|
||||
.TH SPU_CREATE 2 2007-07-10 "Linux" "Linux Programmer's Manual"
|
||||
.TH SPU_CREATE 2 2007-11-25 Linux "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
spu_create \- create a new spu context
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -31,6 +30,8 @@ spu_create \- create a new spu context
|
|||
.B #include <sys/spu.h>
|
||||
|
||||
.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ");"
|
||||
.BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ","
|
||||
.BI " int " neighbor_fd ");"
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
|
|
@ -38,74 +39,149 @@ The
|
|||
system call is used on PowerPC machines that implement the
|
||||
Cell Broadband Engine Architecture in order to access Synergistic
|
||||
Processor Units (SPUs).
|
||||
It creates a new logical context for an
|
||||
SPU in
|
||||
It creates a new logical context for an SPU in
|
||||
.I pathname
|
||||
and returns a file descriptor associated with it.
|
||||
.I pathname
|
||||
must point to a non-existing directory in the mount point of the
|
||||
SPU file system (SPUFS).
|
||||
must refer to a non-existing directory in the mount point of
|
||||
the SPU file system
|
||||
.BR ( spufs ).
|
||||
If
|
||||
.BR spu_create ()
|
||||
is successful, a directory is created in
|
||||
is successful, a directory is created at
|
||||
.I pathname
|
||||
and it is populated with the files described in
|
||||
.BR spufs (7).
|
||||
|
||||
The returned file descriptor can only be passed to
|
||||
When a context is created,
|
||||
the returned file descriptor can only be passed to
|
||||
.BR spu_run (2)
|
||||
or closed;
|
||||
other operations are not defined on it.
|
||||
A logical SPU
|
||||
context is destroyed when its file descriptor is closed as well as
|
||||
all the file descriptors pointing to files inside it.
|
||||
When an SPU context is destroyed all its directory entries in the
|
||||
SPUFS are removed.
|
||||
context is destroyed (along with all files created within the context's
|
||||
.I pathname
|
||||
directory) once the last reference to the context has gone;
|
||||
this usually occurs when the file descriptor returned by
|
||||
.BR spu_create ()
|
||||
is closed.
|
||||
|
||||
The argument
|
||||
The
|
||||
.I flags
|
||||
can be zero or the following
|
||||
constant:
|
||||
argument can be zero or any bitwise OR-ed
|
||||
combination of the following constants:
|
||||
.TP
|
||||
.B SPU_RAWIO
|
||||
Allow mapping of some of the hardware registers of the SPU into user
|
||||
space.
|
||||
This flag requires the
|
||||
.B CAP_SYS_RAWIO
|
||||
.B SPU_CREATE_EVENTS_ENABLED
|
||||
Rather than using signals for reporting DMA errors, use the
|
||||
.I event
|
||||
argument to
|
||||
.BR spu_run (2) .
|
||||
.TP
|
||||
.B SPU_CREATE_GANG
|
||||
Create an SPU gang instead of a context.
|
||||
(A gang is a group of SPU contexts that are
|
||||
functionally related to each other and which share common scheduling
|
||||
parameters \(em priority and policy.
|
||||
In the future, gang scheduling may be implemented causing
|
||||
the group to be switched in and out as a single unit.)
|
||||
|
||||
A new directory will be created at the location specified by the
|
||||
.I pathname
|
||||
argument.
|
||||
This gang may be used to hold other SPU contexts, by providing
|
||||
a pathname that is within the gang directory to further calls to
|
||||
.BR spu_create (2).
|
||||
.TP
|
||||
.B SPU_CREATE_NOSCHED
|
||||
Create a context that is not affected by the SPU scheduler.
|
||||
Once the context is run,
|
||||
it will not be scheduled out until it is destroyed by
|
||||
the creating process.
|
||||
|
||||
Because the context cannot be removed from the SPU, some functionality
|
||||
is disabled for NOSCHED contexts.
|
||||
Only a subset of the files will be
|
||||
available in this context directory in spufs.
|
||||
Additionally, NOSCHED contexts cannot dump a core file when crashing.
|
||||
|
||||
Creating NOSCHED contexts requires the
|
||||
.B CAP_SYS_NICE
|
||||
capability.
|
||||
.TP
|
||||
.B SPU_CREATE_ISOLATE
|
||||
Create an isolated SPU context.
|
||||
Isolated contexts are protected from some
|
||||
PPE (PowerPC Processing Element)
|
||||
operations,
|
||||
such as access to the SPU local store and the NPC register.
|
||||
|
||||
Creating
|
||||
.B SPU_CREATE_ISOLATE
|
||||
contexts also requires the
|
||||
.B SPU_CREATE_NOSCHED
|
||||
flag.
|
||||
.TP
|
||||
.B SPU_CREATE_AFFINITY_SPU
|
||||
Create a context with affinity to another SPU context.
|
||||
This affinity information is used within the SPU scheduling algorithm.
|
||||
Using this flag requires that a file descriptor referring to
|
||||
the other SPU context be passed in the
|
||||
.I neighbor_fd
|
||||
argument.
|
||||
.TP
|
||||
.B SPU_CREATE_AFFINITY_MEM
|
||||
Create a context with affinity to system memory.
|
||||
This affinity information
|
||||
is used within the SPU scheduling algorithm.
|
||||
.PP
|
||||
The new directory and files are created in the SPUFS with the
|
||||
permissions set by the
|
||||
The
|
||||
.I mode
|
||||
argument minus those set in the process's
|
||||
.BR umask (2).
|
||||
The actual permissions set for each file also depend on whether the
|
||||
file supports read and/or write accesses.
|
||||
argument (minus any bits set in the process's
|
||||
.BR umask (2))
|
||||
specifies the permissions used for creating the new directory in
|
||||
spufs.
|
||||
See
|
||||
.BR stat (2)
|
||||
for a full list of the possible
|
||||
.I mode
|
||||
values.
|
||||
.SH RETURN VALUE
|
||||
On success,
|
||||
.BR spu_create (2)
|
||||
returns a new file descriptor.
|
||||
On error, \-1 is returned and
|
||||
On error, \-1 is returned, and
|
||||
.I errno
|
||||
is set to one of the error codes listed below.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EACCES
|
||||
The current user does not have write access to the SPUFS mount point.
|
||||
The current user does not have write access to the
|
||||
.BR spufs (7)
|
||||
mount point.
|
||||
.TP
|
||||
.B EPERM
|
||||
The
|
||||
.I SPU_CREATE_NOSCHED
|
||||
flag has been given, but the user does not have the
|
||||
.B CAP_SYS_NICE
|
||||
capability.
|
||||
.TP
|
||||
.B EEXIST
|
||||
An SPU context already exists in the given path name.
|
||||
An SPU context already exists at the given path name.
|
||||
.TP
|
||||
.B EFAULT
|
||||
.I pathname
|
||||
is not a valid string pointer in the current address space.
|
||||
is not a valid string pointer in the
|
||||
calling process's address space.
|
||||
.TP
|
||||
.B EINVAL
|
||||
.I pathname
|
||||
is not a directory in the SPUFS mount point.
|
||||
is not a directory in the
|
||||
.BR spufs (7)
|
||||
mount point, or invalid flags have been provided.
|
||||
.TP
|
||||
.B ELOOP
|
||||
Too many symlinks were found while resolving
|
||||
Too many symbolic links were found while resolving
|
||||
.IR pathname .
|
||||
.TP
|
||||
.B EMFILE
|
||||
|
|
@ -118,6 +194,10 @@ is too long.
|
|||
.B ENFILE
|
||||
The system has reached the global open files limit.
|
||||
.TP
|
||||
.B ENODEV
|
||||
An isolated context was requested, but the hardware does not support
|
||||
SPU isolation.
|
||||
.TP
|
||||
.B ENOENT
|
||||
Part of
|
||||
.I pathname
|
||||
|
|
@ -128,7 +208,7 @@ The kernel could not allocate all resources required.
|
|||
.TP
|
||||
.B ENOSPC
|
||||
There are not enough SPU resources available to create
|
||||
a new context or the user specific limit for the number
|
||||
a new context or the user-specific limit for the number
|
||||
of SPU contexts has been reached.
|
||||
.TP
|
||||
.B ENOSYS
|
||||
|
|
@ -142,7 +222,8 @@ A part of
|
|||
is not a directory.
|
||||
.SH FILES
|
||||
.I pathname
|
||||
must point to a location beneath the mount point of the SPUFS.
|
||||
must point to a location beneath the mount point of
|
||||
.BR spufs .
|
||||
By convention, it gets mounted in
|
||||
.IR /spu .
|
||||
.SH VERSIONS
|
||||
|
|
@ -150,7 +231,7 @@ The
|
|||
.BR spu_create (2)
|
||||
system call was added to Linux in kernel 2.6.16.
|
||||
.SH CONFORMING TO
|
||||
This call is Linux specific and only implemented by the ppc64
|
||||
This call is Linux specific and only implemented on the PowerPC
|
||||
architecture.
|
||||
Programs using this system call are not portable.
|
||||
.SH NOTES
|
||||
|
|
@ -163,10 +244,11 @@ interface to SPUs, not to be used from regular applications.
|
|||
See
|
||||
.I http://www.bsc.es/projects/deepcomputing/linuxoncell/
|
||||
for the recommended libraries.
|
||||
.SH BUGS
|
||||
The code does not yet fully implement all features outlined here.
|
||||
.\" .SH AUTHOR
|
||||
.\" Arnd Bergmann <arndb@de.ibm.com>
|
||||
.SH EXAMPLE
|
||||
See
|
||||
.BR spu_run (2)
|
||||
for an example of the use of
|
||||
.BR spu_create ()
|
||||
.SH SEE ALSO
|
||||
.BR close (2),
|
||||
.BR spu_run (2),
|
||||
|
|
|
|||
184
man2/spu_run.2
184
man2/spu_run.2
|
|
@ -1,19 +1,17 @@
|
|||
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
||||
.\" Copyright (c) International Business Machines Corp., 2006
|
||||
.\"
|
||||
.\" Copyright (c) International Business Machines Corp., 2006
|
||||
.\"
|
||||
.\" This program is free software; you can redistribute it and/or
|
||||
.\" This program is free software; you can redistribute it and/or
|
||||
.\" modify it under the terms of the GNU General Public License as
|
||||
.\" published by the Free Software Foundation; either version 2 of
|
||||
.\" the License, or (at your option) any later version.
|
||||
.\"
|
||||
.\" This program is distributed in the hope that it will be useful,
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
||||
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
||||
.\" the GNU General Public License for more details.
|
||||
.\"
|
||||
.\" You should have received a copy of the GNU General Public License
|
||||
.\" along with this program; if not, write to the Free Software
|
||||
.\" along with this program; if not, write to the Free Software
|
||||
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||
.\" MA 02111-1307 USA
|
||||
.\"
|
||||
|
|
@ -21,8 +19,10 @@
|
|||
.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
|
||||
.\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
|
||||
.\" 2007-07-10, some polishing by mtk
|
||||
.\" 2007-09-28, updates for newer kernels, added example
|
||||
.\" by Jeremy Kerr <jk@ozlabs.org>
|
||||
.\"
|
||||
.TH SPU_RUN 2 2007-07-10 "Linux" "Linux Programmer's Manual"
|
||||
.TH SPU_RUN 2 2007-11-25 Linux "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
spu_run \- execute an spu context
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -42,72 +42,61 @@ The
|
|||
.I fd
|
||||
argument is a file descriptor returned by
|
||||
.BR spu_create (2)
|
||||
that addresses a specific SPU context.
|
||||
When the context gets
|
||||
scheduled to a physical SPU, it starts execution at the instruction
|
||||
pointer passed in
|
||||
that refers to a specific SPU context.
|
||||
When the context gets scheduled to a physical SPU,
|
||||
it starts execution at the instruction pointer passed in
|
||||
.IR npc .
|
||||
|
||||
Execution of SPU code happens synchronously, meaning that
|
||||
.BR spu_run ()
|
||||
does not return while the SPU is still running.
|
||||
blocks while the SPU is still running.
|
||||
If there is a need
|
||||
to execute SPU code in parallel with other code on either the
|
||||
main CPU or other SPUs, a new thread of execution must be created
|
||||
first, using the
|
||||
.BR pthread_create (3)
|
||||
call for instance.
|
||||
first (e.g., using
|
||||
.BR pthread_create (3)).
|
||||
|
||||
When
|
||||
.BR spu_run ()
|
||||
returns, the current value of the SPU instruction pointer is written to
|
||||
returns, the current value of the SPU program counter is written to
|
||||
.IR npc ,
|
||||
so one can call
|
||||
so successive calls to
|
||||
.BR spu_run ()
|
||||
again without having to update the pointers.
|
||||
can use the same
|
||||
.I npc
|
||||
pointer.
|
||||
|
||||
The
|
||||
.I event
|
||||
can be a NULL pointer or a pointer to an to a buffer that
|
||||
argument provides a buffer for an extended status code.
|
||||
If the SPU
|
||||
context was created with the
|
||||
.B SPU_CREATE_EVENTS_ENABLED
|
||||
flag, then this buffer is populated by the Linux kernel before
|
||||
.BR spu_run ()
|
||||
uses to return an extended status code.
|
||||
The status code may be one of the following constants:
|
||||
returns.
|
||||
|
||||
The status code may be one (or more) of the following constants:
|
||||
.TP
|
||||
.B SPE_EVENT_DMA_ALIGNMENT
|
||||
A DMA alignment error occurred
|
||||
.RB ( SIGBUS ,
|
||||
.I si_code
|
||||
set to
|
||||
.BR BUS_ADRALN ).
|
||||
A DMA alignment error occurred.
|
||||
.TP
|
||||
.B SPE_EVENT_INVALID_DMA
|
||||
MFC DMA was invalid
|
||||
.RB ( SIGBUS ,
|
||||
.I si_code
|
||||
set to
|
||||
.BR BUS_OBJERR ).
|
||||
.\" .B SPE_EVENT_SPE_DATA_SEGMENT
|
||||
.\" A DMA segmentation error occurred.
|
||||
An invalid MFC DMA command was attempted.
|
||||
.TP
|
||||
.B SPE_EVENT_SPE_DATA_STORAGE
|
||||
A DMA storage error occurred
|
||||
.RB ( SIGBUS ,
|
||||
.I si_code
|
||||
set to
|
||||
.BR BUS_ADRERR ).
|
||||
A DMA storage error occurred.
|
||||
.TP
|
||||
.B SPE_EVENT_SPE_ERROR
|
||||
Illegal instruction error
|
||||
.RB ( SIGBUS ,
|
||||
.I si_code
|
||||
set to
|
||||
.BR BUS_ADRALN ).
|
||||
An illegal instruction was executed.
|
||||
.PP
|
||||
If
|
||||
NULL
|
||||
is a valid value for the
|
||||
.I event
|
||||
is NULL, these errors will cause the corresponding signal listed
|
||||
above to be delivered to the calling process.
|
||||
argument.
|
||||
In this case, the events will not be reported to the calling process.
|
||||
.SH RETURN VALUE
|
||||
On success
|
||||
On success,
|
||||
.BR spu_run ()
|
||||
returns the value of the
|
||||
.I spu_status
|
||||
|
|
@ -115,22 +104,25 @@ register.
|
|||
On error it returns \-1 and sets
|
||||
.I errno
|
||||
to one of the error codes listed below.
|
||||
|
||||
The
|
||||
.I spu_status
|
||||
register value is a bit mask of status codes and
|
||||
optionally a 14-bit code returned from the stop-and-signal
|
||||
optionally a 14-bit code returned from the
|
||||
.BR stop-and-signal
|
||||
instruction on the SPU.
|
||||
The bit masks for the status codes
|
||||
are:
|
||||
.TP
|
||||
.B 0x02
|
||||
SPU was stopped by stop-and-signal.
|
||||
In this case the 14-bit code
|
||||
returned from the instruction can be retrieved with the mask
|
||||
.IR 0x3fff0000 .
|
||||
SPU was stopped by a
|
||||
.BR stop-and-signal
|
||||
instruction.
|
||||
.TP
|
||||
.B 0x04
|
||||
SPU was stopped by halt.
|
||||
SPU was stopped by a
|
||||
.BR halt
|
||||
instruction.
|
||||
.TP
|
||||
.B 0x08
|
||||
SPU is waiting for a channel.
|
||||
|
|
@ -143,6 +135,12 @@ SPU has tried to execute an invalid instruction.
|
|||
.TP
|
||||
.B 0x40
|
||||
SPU has tried to access an invalid channel.
|
||||
.TP
|
||||
.B 0x3fff0000
|
||||
The bits masked with this value contain the code returned from a
|
||||
.BR stop-and-signal
|
||||
instruction.
|
||||
These bits are only valid if the 0x02 bit is set.
|
||||
.PP
|
||||
If
|
||||
.BR spu_run ()
|
||||
|
|
@ -150,21 +148,15 @@ has not returned an error, one or more bits among the lower eight
|
|||
ones are always set.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.BR EAGAIN " or " EWOULDBLOCK
|
||||
.I fd
|
||||
is in non-blocking mode and
|
||||
.BR spu_run ()
|
||||
would block.
|
||||
.TP
|
||||
.B EBADF
|
||||
.I fd
|
||||
is not a valid file descriptor.
|
||||
.TP
|
||||
.B EFAULT
|
||||
.I npc
|
||||
is not a valid pointer or
|
||||
.I status
|
||||
is neither NULL nor a valid pointer.
|
||||
is not a valid pointer, or
|
||||
.I event
|
||||
is non-NULL and an invalid pointer.
|
||||
.TP
|
||||
.B EINTR
|
||||
A signal occurred while
|
||||
|
|
@ -177,7 +169,7 @@ necessary.
|
|||
.TP
|
||||
.B EINVAL
|
||||
.I fd
|
||||
is not a file descriptor returned from
|
||||
is not a valid file descriptor returned from
|
||||
.BR spu_create (2).
|
||||
.TP
|
||||
.B ENOMEM
|
||||
|
|
@ -193,7 +185,7 @@ The
|
|||
.BR spu_run (2)
|
||||
system call was added to Linux in kernel 2.6.16.
|
||||
.SH CONFORMING TO
|
||||
This call is Linux specific and only implemented by the ppc64
|
||||
This call is Linux specific and only implemented by the PowerPC
|
||||
architecture.
|
||||
Programs using this system call are not portable.
|
||||
.SH NOTES
|
||||
|
|
@ -206,11 +198,65 @@ interface to SPUs, not to be used from regular applications.
|
|||
See
|
||||
.I http://www.bsc.es/projects/deepcomputing/linuxoncell/
|
||||
for the recommended libraries.
|
||||
.SH BUGS
|
||||
The code does not yet fully implement all features outlined here.
|
||||
.\" .SH AUTHOR
|
||||
.\" Arnd Bergmann <arndb@de.ibm.com>
|
||||
.SH EXAMPLE
|
||||
The following is an example of running a simple, one-instruction SPU
|
||||
program with the
|
||||
.BR spu_run ()
|
||||
system call.
|
||||
|
||||
.nf
|
||||
#include <stdlib.h>
|
||||
#include <stdint.h>
|
||||
#include <unistd.h>
|
||||
#include <stdio.h>
|
||||
#include <sys/types.h>
|
||||
#include <fcntl.h>
|
||||
|
||||
#define handle_error(msg) \\
|
||||
do { perror(msg); exit(EXIT_FAILURE); } while (0)
|
||||
|
||||
int main(void)
|
||||
{
|
||||
int context, fd, spu_status;
|
||||
uint32_t instruction, npc;
|
||||
|
||||
context = spu_create("/spu/example\-context", 0, 0755);
|
||||
if (context == -1)
|
||||
handle_error("spu_create");
|
||||
|
||||
/* write a 'stop 0x1234' instruction to the SPU's
|
||||
* local store memory
|
||||
*/
|
||||
instruction = 0x00001234;
|
||||
|
||||
fd = open("/spu/example\-context/mem", O_RDWR);
|
||||
if (fd == -1)
|
||||
handle_error("open");
|
||||
write(fd, &instruction, sizeof(instruction));
|
||||
|
||||
/* set npc to the starting instruction address of the
|
||||
* SPU program. Since we wrote the instruction at the
|
||||
* start of the mem file, the entry point will be 0x0
|
||||
*/
|
||||
npc = 0;
|
||||
|
||||
spu_status = spu_run(context, &npc, NULL);
|
||||
if (spu_status == -1)
|
||||
handle_error("open");
|
||||
|
||||
/* we should see a status code of 0x1234002:
|
||||
* 0x00000002 (spu was stopped due to stop\-and\-signal)
|
||||
* | 0x12340000 (the stop\-and\-signal code)
|
||||
*/
|
||||
printf("SPU Status: 0x%08x\\n", spu_status);
|
||||
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.\" .SH AUTHORS
|
||||
.\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
|
||||
.SH SEE ALSO
|
||||
.BR close (2),
|
||||
.BR spu_create (2),
|
||||
.BR capabilities (7),
|
||||
.BR spufs (7)
|
||||
|
|
|
|||
Loading…
Reference in New Issue