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