manual/LDP_man-pages/original/man2/spu_create.2

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