spu_run.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=======
  4spu_run
  5=======
  6
  7
  8Name
  9====
 10       spu_run - execute an spu context
 11
 12
 13Synopsis
 14========
 15
 16       ::
 17
 18	    #include <sys/spu.h>
 19
 20	    int spu_run(int fd, unsigned int *npc, unsigned int *event);
 21
 22Description
 23===========
 24       The  spu_run system call is used on PowerPC machines that implement the
 25       Cell Broadband Engine Architecture in order to access Synergistic  Pro-
 26       cessor  Units  (SPUs).  It  uses the fd that was returned from spu_cre-
 27       ate(2) to address a specific SPU context. When the context gets  sched-
 28       uled  to a physical SPU, it starts execution at the instruction pointer
 29       passed in npc.
 30
 31       Execution of SPU code happens synchronously, meaning that spu_run  does
 32       not  return  while the SPU is still running. If there is a need to exe-
 33       cute SPU code in parallel with other code on either  the  main  CPU  or
 34       other  SPUs,  you  need to create a new thread of execution first, e.g.
 35       using the pthread_create(3) call.
 36
 37       When spu_run returns, the current value of the SPU instruction  pointer
 38       is  written back to npc, so you can call spu_run again without updating
 39       the pointers.
 40
 41       event can be a NULL pointer or point to an extended  status  code  that
 42       gets  filled  when spu_run returns. It can be one of the following con-
 43       stants:
 44
 45       SPE_EVENT_DMA_ALIGNMENT
 46              A DMA alignment error
 47
 48       SPE_EVENT_SPE_DATA_SEGMENT
 49              A DMA segmentation error
 50
 51       SPE_EVENT_SPE_DATA_STORAGE
 52              A DMA storage error
 53
 54       If NULL is passed as the event argument, these errors will result in  a
 55       signal delivered to the calling process.
 56
 57Return Value
 58============
 59       spu_run  returns the value of the spu_status register or -1 to indicate
 60       an error and set errno to one of the error  codes  listed  below.   The
 61       spu_status  register  value  contains  a  bit  mask of status codes and
 62       optionally a 14 bit code returned from the stop-and-signal  instruction
 63       on the SPU. The bit masks for the status codes are:
 64
 65       0x02
 66	      SPU was stopped by stop-and-signal.
 67
 68       0x04
 69	      SPU was stopped by halt.
 70
 71       0x08
 72	      SPU is waiting for a channel.
 73
 74       0x10
 75	      SPU is in single-step mode.
 76
 77       0x20
 78	      SPU has tried to execute an invalid instruction.
 79
 80       0x40
 81	      SPU has tried to access an invalid channel.
 82
 83       0x3fff0000
 84              The  bits  masked with this value contain the code returned from
 85              stop-and-signal.
 86
 87       There are always one or more of the lower eight bits set  or  an  error
 88       code is returned from spu_run.
 89
 90Errors
 91======
 92       EAGAIN or EWOULDBLOCK
 93              fd is in non-blocking mode and spu_run would block.
 94
 95       EBADF  fd is not a valid file descriptor.
 96
 97       EFAULT npc is not a valid pointer or status is neither NULL nor a valid
 98              pointer.
 99
100       EINTR  A signal occurred while spu_run was in progress.  The npc  value
101              has  been updated to the new program counter value if necessary.
102
103       EINVAL fd is not a file descriptor returned from spu_create(2).
104
105       ENOMEM Insufficient memory was available to handle a page fault result-
106              ing from an MFC direct memory access.
107
108       ENOSYS the functionality is not provided by the current system, because
109              either the hardware does not provide SPUs or the spufs module is
110              not loaded.
111
112
113Notes
114=====
115       spu_run  is  meant  to  be  used  from  libraries that implement a more
116       abstract interface to SPUs, not to be used from  regular  applications.
117       See  http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
118       ommended libraries.
119
120
121Conforming to
122=============
123       This call is Linux specific and only implemented by the ppc64 architec-
124       ture. Programs using this system call are not portable.
125
126
127Bugs
128====
129       The code does not yet fully implement all features lined out here.
130
131
132Author
133======
134       Arnd Bergmann <arndb@de.ibm.com>
135
136See Also
137========
138       capabilities(7), close(2), spu_create(2), spufs(7)