original/man2/spu_run.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, added example
  24 .\"             by Jeremy Kerr <jk@ozlabs.org>
  25 .\"
  26 .TH SPU_RUN 2 2012-08-05 Linux "Linux Programmer's Manual"
  27 .SH NAME
  28 spu_run \- execute an SPU context
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <sys/spu.h>
  32
  33 .BI "int spu_run(int " fd ", unsigned int *" npc \
  34 ", unsigned int *" event ");"
  35 .fi
  36
  37 .IR Note :
  38 There is no glibc wrapper for this system call; see NOTES.
  39 .SH DESCRIPTION
  40 The
  41 .BR spu_run ()
  42 system call is used on PowerPC machines that implement the
  43 Cell Broadband Engine Architecture in order to access Synergistic
  44 Processor Units (SPUs).
  45 The
  46 .I fd
  47 argument is a file descriptor returned by
  48 .BR spu_create (2)
  49 that refers to a specific SPU context.
  50 When the context gets scheduled to a physical SPU,
  51 it starts execution at the instruction pointer passed in
  52 .IR npc .
  53
  54 Execution of SPU code happens synchronously, meaning that
  55 .BR spu_run ()
  56 blocks while the SPU is still running.
  57 If there is a need
  58 to execute SPU code in parallel with other code on either the
  59 main CPU or other SPUs, a new thread of execution must be created
  60 first (e.g., using
  61 .BR pthread_create (3)).
  62
  63 When
  64 .BR spu_run ()
  65 returns, the current value of the SPU program counter is written to
  66 .IR npc ,
  67 so successive calls to
  68 .BR spu_run ()
  69 can use the same
  70 .I npc
  71 pointer.
  72
  73 The
  74 .I event
  75 argument provides a buffer for an extended status code.
  76 If the SPU
  77 context was created with the
  78 .B SPU_CREATE_EVENTS_ENABLED
  79 flag, then this buffer is populated by the Linux kernel before
  80 .BR spu_run ()
  81 returns.
  82
  83 The status code may be one (or more) of the following constants:
  84 .TP
  85 .B SPE_EVENT_DMA_ALIGNMENT
  86 A DMA alignment error occurred.
  87 .TP
  88 .B SPE_EVENT_INVALID_DMA
  89 An invalid MFC DMA command was attempted.
  90 .TP
  91 .B SPE_EVENT_SPE_DATA_STORAGE
  92 A DMA storage error occurred.
  93 .TP
  94 .B SPE_EVENT_SPE_ERROR
  95 An illegal instruction was executed.
  96 .PP
  97 NULL
  98 is a valid value for the
  99 .I event
 100 argument.
 101 In this case, the events will not be reported to the calling process.
 102 .SH RETURN VALUE
 103 On success,
 104 .BR spu_run ()
 105 returns the value of the
 106 .I spu_status
 107 register.
 108 On error, it returns \-1 and sets
 109 .I errno
 110 to one of the error codes listed below.
 111
 112 The
 113 .I spu_status
 114 register value is a bit mask of status codes and
 115 optionally a 14-bit code returned from the
 116 .BR stop-and-signal
 117 instruction on the SPU.
 118 The bit masks for the status codes
 119 are:
 120 .TP
 121 .B 0x02
 122 SPU was stopped by a
 123 .BR stop-and-signal
 124 instruction.
 125 .TP
 126 .B 0x04
 127 SPU was stopped by a
 128 .BR halt
 129 instruction.
 130 .TP
 131 .B 0x08
 132 SPU is waiting for a channel.
 133 .TP
 134 .B 0x10
 135 SPU is in single-step mode.
 136 .TP
 137 .B 0x20
 138 SPU has tried to execute an invalid instruction.
 139 .TP
 140 .B 0x40
 141 SPU has tried to access an invalid channel.
 142 .TP
 143 .B 0x3fff0000
 144 The bits masked with this value contain the code returned from a
 145 .BR stop-and-signal
 146 instruction.
 147 These bits are valid only if the 0x02 bit is set.
 148 .PP
 149 If
 150 .BR spu_run ()
 151 has not returned an error, one or more bits among the lower eight
 152 ones are always set.
 153 .SH ERRORS
 154 .TP
 155 .B EBADF
 156 .I fd
 157 is not a valid file descriptor.
 158 .TP
 159 .B EFAULT
 160 .I npc
 161 is not a valid pointer, or
 162 .I event
 163 is non-NULL and an invalid pointer.
 164 .TP
 165 .B EINTR
 166 A signal occurred while
 167 .BR spu_run ()
 168 was in progress; see
 169 .BR signal (7).
 170 The
 171 .I npc
 172 value has been updated to the new program counter value if
 173 necessary.
 174 .TP
 175 .B EINVAL
 176 .I fd
 177 is not a valid file descriptor returned from
 178 .BR spu_create (2).
 179 .TP
 180 .B ENOMEM
 181 There was not enough memory available to handle a page fault
 182 resulting from a Memory Flow Controller (MFC) direct memory access.
 183 .TP
 184 .B ENOSYS
 185 The functionality is not provided by the current system, because
 186 either the hardware does not provide SPUs or the spufs module is not
 187 loaded.
 188 .SH VERSIONS
 189 The
 190 .BR spu_run ()
 191 system call was added to Linux in kernel 2.6.16.
 192 .SH CONFORMING TO
 193 This call is Linux-specific and implemented only by the PowerPC
 194 architecture.
 195 Programs using this system call are not portable.
 196 .SH NOTES
 197 Glibc does not provide a wrapper for this system call; call it using
 198 .BR syscall (2).
 199 Note however, that
 200 .BR spu_run ()
 201 is meant to be used from libraries that implement a more abstract
 202 interface to SPUs, not to be used from regular applications.
 203 See
 204 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
 205 .UE
 206 for the recommended libraries.
 207 .SH EXAMPLE
 208 The following is an example of running a simple, one-instruction SPU
 209 program with the
 210 .BR spu_run ()
 211 system call.
 212
 213 .nf
 214 #include <stdlib.h>
 215 #include <stdint.h>
 216 #include <unistd.h>
 217 #include <stdio.h>
 218 #include <sys/types.h>
 219 #include <fcntl.h>
 220
 221 #define handle_error(msg) \\
 222     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 223
 224 int main(void)
 225 {
 226     int context, fd, spu_status;
 227     uint32_t instruction, npc;
 228
 229     context = spu_create("/spu/example\-context", 0, 0755);
 230     if (context == \-1)
 231         handle_error("spu_create");
 232
 233     /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
 234      * local store memory
 235      */
 236     instruction = 0x00001234;
 237
 238     fd = open("/spu/example\-context/mem", O_RDWR);
 239     if (fd == \-1)
 240         handle_error("open");
 241     write(fd, &instruction, sizeof(instruction));
 242
 243     /* set npc to the starting instruction address of the
 244      * SPU program. Since we wrote the instruction at the
 245      * start of the mem file, the entry point will be 0x0
 246      */
 247     npc = 0;
 248
 249     spu_status = spu_run(context, &npc, NULL);
 250     if (spu_status == \-1)
 251         handle_error("open");
 252
 253     /* we should see a status code of 0x1234002:
 254      *   0x00000002 (spu was stopped due to stop\-and\-signal)
 255      * | 0x12340000 (the stop\-and\-signal code)
 256      */
 257     printf("SPU Status: 0x%08x\\n", spu_status);
 258
 259     exit(EXIT_SUCCESS);
 260 }
 261 .fi
 262 .\" .SH AUTHORS
 263 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 264 .SH SEE ALSO
 265 .BR close (2),
 266 .BR spu_create (2),
 267 .BR capabilities (7),
 268 .BR spufs (7)
 269 .SH COLOPHON
 270 This page is part of release 3.79 of the Linux
 271 .I man-pages
 272 project.
 273 A description of the project,
 274 information about reporting bugs,
 275 and the latest version of this page,
 276 can be found at
 277 \%http://www.kernel.org/doc/man\-pages/.