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)
139