original/man2/spu_create.2

   1 .\" Copyright (c) International Business Machines Corp., 2006
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   4 .\" This program is free software; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12 .\" the GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public
  15 .\" License along with this manual; if not, see
  16 .\" <http://www.gnu.org/licenses/>.
  17 .\" %%%LICENSE_END
  18 .\"
  19 .\" HISTORY:
  20 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
  21 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
  22 .\" 2007-07-10, some polishing by mtk
  23 .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
  24 .\"
  25 .TH SPU_CREATE 2 2012-08-05 Linux "Linux Programmer's Manual"
  26 .SH NAME
  27 spu_create \- create a new spu context
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/types.h>
  31 .B #include <sys/spu.h>
  32
  33 .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ");"
  34 .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ","
  35 .BI "               int " neighbor_fd ");"
  36 .fi
  37
  38 .IR Note :
  39 There is no glibc wrapper for this system call; see NOTES.
  40 .SH DESCRIPTION
  41 The
  42 .BR spu_create ()
  43 system call is used on PowerPC machines that implement the
  44 Cell Broadband Engine Architecture in order to access Synergistic
  45 Processor Units (SPUs).
  46 It creates a new logical context for an SPU in
  47 .I pathname
  48 and returns a file descriptor associated with it.
  49 .I pathname
  50 must refer to a nonexistent directory in the mount point of
  51 the SPU filesystem
  52 .RB ( spufs ).
  53 If
  54 .BR spu_create ()
  55 is successful, a directory is created at
  56 .I pathname
  57 and it is populated with the files described in
  58 .BR spufs (7).
  59
  60 When a context is created,
  61 the returned file descriptor can only be passed to
  62 .BR spu_run (2),
  63 used as the
  64 .I dirfd
  65 argument to the
  66 .B *at
  67 family of system calls (e.g.,
  68 .BR openat (2)),
  69 or closed;
  70 other operations are not defined.
  71 A logical SPU
  72 context is destroyed (along with all files created within the context's
  73 .I pathname
  74 directory) once the last reference to the context has gone;
  75 this usually occurs when the file descriptor returned by
  76 .BR spu_create ()
  77 is closed.
  78
  79 The
  80 .I flags
  81 argument can be zero or any bitwise OR-ed
  82 combination of the following constants:
  83 .TP
  84 .B SPU_CREATE_EVENTS_ENABLED
  85 Rather than using signals for reporting DMA errors, use the
  86 .I event
  87 argument to
  88 .BR spu_run (2).
  89 .TP
  90 .B SPU_CREATE_GANG
  91 Create an SPU gang instead of a context.
  92 (A gang is a group of SPU contexts that are
  93 functionally related to each other and which share common scheduling
  94 parameters\(empriority and policy.
  95 In the future, gang scheduling may be implemented causing
  96 the group to be switched in and out as a single unit.)
  97
  98 A new directory will be created at the location specified by the
  99 .I pathname
 100 argument.
 101 This gang may be used to hold other SPU contexts, by providing
 102 a pathname that is within the gang directory to further calls to
 103 .BR spu_create ().
 104 .TP
 105 .B SPU_CREATE_NOSCHED
 106 Create a context that is not affected by the SPU scheduler.
 107 Once the context is run,
 108 it will not be scheduled out until it is destroyed by
 109 the creating process.
 110
 111 Because the context cannot be removed from the SPU, some functionality
 112 is disabled for
 113 .BR SPU_CREATE_NOSCHED
 114 contexts.
 115 Only a subset of the files will be
 116 available in this context directory in
 117 .BR spufs .
 118 Additionally,
 119 .BR SPU_CREATE_NOSCHED
 120 contexts cannot dump a core file when crashing.
 121
 122 Creating
 123 .BR SPU_CREATE_NOSCHED
 124 contexts requires the
 125 .B CAP_SYS_NICE
 126 capability.
 127 .TP
 128 .B SPU_CREATE_ISOLATE
 129 Create an isolated SPU context.
 130 Isolated contexts are protected from some
 131 PPE (PowerPC Processing Element)
 132 operations,
 133 such as access to the SPU local store and the NPC register.
 134
 135 Creating
 136 .B SPU_CREATE_ISOLATE
 137 contexts also requires the
 138 .B SPU_CREATE_NOSCHED
 139 flag.
 140 .TP
 141 .B SPU_CREATE_AFFINITY_SPU
 142 Create a context with affinity to another SPU context.
 143 This affinity information is used within the SPU scheduling algorithm.
 144 Using this flag requires that a file descriptor referring to
 145 the other SPU context be passed in the
 146 .I neighbor_fd
 147 argument.
 148 .TP
 149 .B SPU_CREATE_AFFINITY_MEM
 150 Create a context with affinity to system memory.
 151 This affinity information
 152 is used within the SPU scheduling algorithm.
 153 .PP
 154 The
 155 .I mode
 156 argument (minus any bits set in the process's
 157 .BR umask (2))
 158 specifies the permissions used for creating the new directory in
 159 .BR spufs .
 160 See
 161 .BR stat (2)
 162 for a full list of the possible
 163 .I mode
 164 values.
 165 .SH RETURN VALUE
 166 On success,
 167 .BR spu_create ()
 168 returns a new file descriptor.
 169 On error, \-1 is returned, and
 170 .I errno
 171 is set to one of the error codes listed below.
 172 .SH ERRORS
 173 .TP
 174 .B EACCES
 175 The current user does not have write access to the
 176 .BR spufs (7)
 177 mount point.
 178 .TP
 179 .B EEXIST
 180 An SPU context already exists at the given pathname.
 181 .TP
 182 .B EFAULT
 183 .I pathname
 184 is not a valid string pointer in the
 185 calling process's address space.
 186 .TP
 187 .B EINVAL
 188 .I pathname
 189 is not a directory in the
 190 .BR spufs (7)
 191 mount point, or invalid flags have been provided.
 192 .TP
 193 .B ELOOP
 194 Too many symbolic links were found while resolving
 195 .IR pathname .
 196 .TP
 197 .B EMFILE
 198 The process has reached its maximum open files limit.
 199 .TP
 200 .B ENAMETOOLONG
 201 .I pathname
 202 is too long.
 203 .TP
 204 .B ENFILE
 205 The system has reached the global open files limit.
 206 .TP
 207 .B ENODEV
 208 An isolated context was requested, but the hardware does not support
 209 SPU isolation.
 210 .TP
 211 .B ENOENT
 212 Part of
 213 .I pathname
 214 could not be resolved.
 215 .TP
 216 .B ENOMEM
 217 The kernel could not allocate all resources required.
 218 .TP
 219 .B ENOSPC
 220 There are not enough SPU resources available to create
 221 a new context or the user-specific limit for the number
 222 of SPU contexts has been reached.
 223 .TP
 224 .B ENOSYS
 225 The functionality is not provided by the current system, because
 226 either the hardware does not provide SPUs or the spufs module is not
 227 loaded.
 228 .TP
 229 .B ENOTDIR
 230 A part of
 231 .I pathname
 232 is not a directory.
 233 .TP
 234 .B EPERM
 235 The
 236 .I SPU_CREATE_NOSCHED
 237 flag has been given, but the user does not have the
 238 .B CAP_SYS_NICE
 239 capability.
 240 .SH FILES
 241 .I pathname
 242 must point to a location beneath the mount point of
 243 .BR spufs .
 244 By convention, it gets mounted in
 245 .IR /spu .
 246 .SH VERSIONS
 247 The
 248 .BR spu_create ()
 249 system call was added to Linux in kernel 2.6.16.
 250 .SH CONFORMING TO
 251 This call is Linux-specific and implemented only on the PowerPC
 252 architecture.
 253 Programs using this system call are not portable.
 254 .SH NOTES
 255 Glibc does not provide a wrapper for this system call; call it using
 256 .BR syscall (2).
 257 Note however, that
 258 .BR spu_create ()
 259 is meant to be used from libraries that implement a more abstract
 260 interface to SPUs, not to be used from regular applications.
 261 See
 262 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
 263 .UE
 264 for the recommended libraries.
 265 .SH EXAMPLE
 266 See
 267 .BR spu_run (2)
 268 for an example of the use of
 269 .BR spu_create ()
 270 .SH SEE ALSO
 271 .BR close (2),
 272 .BR spu_run (2),
 273 .BR capabilities (7),
 274 .BR spufs (7)
 275 .SH COLOPHON
 276 This page is part of release 3.79 of the Linux
 277 .I man-pages
 278 project.
 279 A description of the project,
 280 information about reporting bugs,
 281 and the latest version of this page,
 282 can be found at
 283 \%http://www.kernel.org/doc/man\-pages/.