1SPU_CREATE(2)              Linux Programmer's Manual             SPU_CREATE(2)
2
3
4

NAME

6       spu_create - create a new spu context
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/spu.h>
11
12       int spu_create(const char *pathname, int flags, mode_t mode);
13       int spu_create(const char *pathname, int flags, mode_t mode,
14                      int neighbor_fd);
15

DESCRIPTION

17       The spu_create() system call is used on PowerPC machines that implement
18       the Cell Broadband Engine Architecture in order to  access  Synergistic
19       Processor Units (SPUs).  It creates a new logical context for an SPU in
20       pathname and returns a file descriptor associated  with  it.   pathname
21       must  refer  to  a non-existing directory in the mount point of the SPU
22       file system (spufs).  If spu_create() is  successful,  a  directory  is
23       created  at  pathname  and  it is populated with the files described in
24       spufs(7).
25
26       When a context is created, the returned file  descriptor  can  only  be
27       passed  to  spu_run(2), used as the dirfd argument to the *at family of
28       system calls (e.g., openat(2)), or closed;  other  operations  are  not
29       defined.  A logical SPU context is destroyed (along with all files cre‐
30       ated within the context's pathname directory) once the  last  reference
31       to  the  context has gone; this usually occurs when the file descriptor
32       returned by spu_create() is closed.
33
34       The flags argument can be zero or any bitwise OR-ed combination of  the
35       following constants:
36
37       SPU_CREATE_EVENTS_ENABLED
38              Rather  than  using  signals  for  reporting DMA errors, use the
39              event argument to spu_run(2).
40
41       SPU_CREATE_GANG
42              Create an SPU gang instead of a context.  (A gang is a group  of
43              SPU  contexts  that  are  functionally related to each other and
44              which share common scheduling parameters — priority and  policy.
45              In  the  future,  gang scheduling may be implemented causing the
46              group to be switched in and out as a single unit.)
47
48              A new directory will be created at the location specified by the
49              pathname argument.  This gang may be used to hold other SPU con‐
50              texts, by providing a pathname that is within the gang directory
51              to further calls to spu_create().
52
53       SPU_CREATE_NOSCHED
54              Create  a  context  that  is  not affected by the SPU scheduler.
55              Once the context is run, it will not be scheduled out  until  it
56              is destroyed by the creating process.
57
58              Because  the  context cannot be removed from the SPU, some func‐
59              tionality is disabled for SPU_CREATE_NOSCHED contexts.   Only  a
60              subset  of the files will be available in this context directory
61              in spufs.  Additionally, SPU_CREATE_NOSCHED contexts cannot dump
62              a core file when crashing.
63
64              Creating  SPU_CREATE_NOSCHED  contexts requires the CAP_SYS_NICE
65              capability.
66
67       SPU_CREATE_ISOLATE
68              Create an isolated SPU context.  Isolated contexts are protected
69              from  some  PPE (PowerPC Processing Element) operations, such as
70              access to the SPU local store and the NPC register.
71
72              Creating SPU_CREATE_ISOLATE contexts also requires the  SPU_CRE‐
73              ATE_NOSCHED flag.
74
75       SPU_CREATE_AFFINITY_SPU
76              Create  a  context  with  affinity to another SPU context.  This
77              affinity information is used within  the  SPU  scheduling  algo‐
78              rithm.   Using  this flag requires that a file descriptor refer‐
79              ring to the other SPU context be passed in the neighbor_fd argu‐
80              ment.
81
82       SPU_CREATE_AFFINITY_MEM
83              Create  a context with affinity to system memory.  This affinity
84              information is used within the SPU scheduling algorithm.
85
86       The mode argument (minus any bits set in the process's umask(2)) speci‐
87       fies the permissions used for creating the new directory in spufs.  See
88       stat(2) for a full list of the possible mode values.
89

RETURN VALUE

91       On success, spu_create() returns a new file descriptor.  On  error,  -1
92       is returned, and errno is set to one of the error codes listed below.
93

ERRORS

95       EACCES The  current  user  does  not  have write access to the spufs(7)
96              mount point.
97
98       EEXIST An SPU context already exists at the given path name.
99
100       EFAULT pathname is not a valid string pointer in the calling  process's
101              address space.
102
103       EINVAL pathname  is  not  a  directory  in the spufs(7) mount point, or
104              invalid flags have been provided.
105
106       ELOOP  Too many symbolic links were found while resolving pathname.
107
108       EMFILE The process has reached its maximum open files limit.
109
110       ENAMETOOLONG
111              pathname is too long.
112
113       ENFILE The system has reached the global open files limit.
114
115       ENODEV An isolated context was requested, but  the  hardware  does  not
116              support SPU isolation.
117
118       ENOENT Part of pathname could not be resolved.
119
120       ENOMEM The kernel could not allocate all resources required.
121
122       ENOSPC There  are  not  enough  SPU resources available to create a new
123              context or the user-specific limit for the number  of  SPU  con‐
124              texts has been reached.
125
126       ENOSYS The functionality is not provided by the current system, because
127              either the hardware does not provide SPUs or the spufs module is
128              not loaded.
129
130       ENOTDIR
131              A part of pathname is not a directory.
132
133       EPERM  The  SPU_CREATE_NOSCHED  flag  has been given, but the user does
134              not have the CAP_SYS_NICE capability.
135

FILES

137       pathname must point to a location beneath the mount point of spufs.  By
138       convention, it gets mounted in /spu.
139

VERSIONS

141       The spu_create() system call was added to Linux in kernel 2.6.16.
142

CONFORMING TO

144       This  call is Linux-specific and only implemented on the PowerPC archi‐
145       tecture.  Programs using this system call are not portable.
146

NOTES

148       Glibc does not provide a wrapper for this system call;  call  it  using
149       syscall(2).   Note  however, that spu_create() is meant to be used from
150       libraries that implement a more abstract interface to SPUs, not  to  be
151       used  from  regular applications.  See http://www.bsc.es/projects/deep
152       computing/linuxoncell/ for the recommended libraries.
153

EXAMPLE

155       See spu_run(2) for an example of the use of spu_create()
156

SEE ALSO

158       close(2), spu_run(2), capabilities(7), spufs(7)
159

COLOPHON

161       This page is part of release 3.22 of the Linux  man-pages  project.   A
162       description  of  the project, and information about reporting bugs, can
163       be found at http://www.kernel.org/doc/man-pages/.
164
165
166
167Linux                             2007-12-20                     SPU_CREATE(2)
Impressum