]>
Commit | Line | Data |
---|---|---|
d24596d5 | 1 | .\" Copyright (c) International Business Machines Corp., 2006 |
f9f7c042 | 2 | .\" |
f0008367 | 3 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
d24596d5 | 4 | .\" This program is free software; you can redistribute it and/or |
f9f7c042 MK |
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, | |
d24596d5 MK |
10 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | |
f9f7c042 MK |
12 | .\" the GNU General Public License for more details. |
13 | .\" | |
68fa4398 MK |
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/>. | |
8ff7380d | 17 | .\" %%%LICENSE_END |
f9f7c042 MK |
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 | |
d24596d5 MK |
23 | .\" 2007-09-28, updates for newer kernels, added example |
24 | .\" by Jeremy Kerr <jk@ozlabs.org> | |
f9f7c042 | 25 | .\" |
9ba01802 | 26 | .TH SPU_RUN 2 2019-03-06 Linux "Linux Programmer's Manual" |
f9f7c042 | 27 | .SH NAME |
763f0e47 | 28 | spu_run \- execute an SPU context |
f9f7c042 MK |
29 | .SH SYNOPSIS |
30 | .nf | |
31 | .B #include <sys/spu.h> | |
dbfe9c70 | 32 | .PP |
f9f7c042 MK |
33 | .BI "int spu_run(int " fd ", unsigned int *" npc \ |
34 | ", unsigned int *" event ");" | |
35 | .fi | |
dbfe9c70 | 36 | .PP |
45c99e3e MK |
37 | .IR Note : |
38 | There is no glibc wrapper for this system call; see NOTES. | |
f9f7c042 | 39 | .SH DESCRIPTION |
e0bf9127 | 40 | The |
f9f7c042 | 41 | .BR spu_run () |
e0bf9127 MK |
42 | system call is used on PowerPC machines that implement the |
43 | Cell Broadband Engine Architecture in order to access Synergistic | |
f9f7c042 MK |
44 | Processor Units (SPUs). |
45 | The | |
46 | .I fd | |
e0bf9127 | 47 | argument is a file descriptor returned by |
f9f7c042 | 48 | .BR spu_create (2) |
d24596d5 MK |
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 | |
f9f7c042 | 52 | .IR npc . |
efeece04 | 53 | .PP |
e0bf9127 | 54 | Execution of SPU code happens synchronously, meaning that |
f9f7c042 | 55 | .BR spu_run () |
d24596d5 | 56 | blocks while the SPU is still running. |
f9f7c042 | 57 | If there is a need |
e0bf9127 | 58 | to execute SPU code in parallel with other code on either the |
f9f7c042 | 59 | main CPU or other SPUs, a new thread of execution must be created |
d24596d5 MK |
60 | first (e.g., using |
61 | .BR pthread_create (3)). | |
efeece04 | 62 | .PP |
f9f7c042 MK |
63 | When |
64 | .BR spu_run () | |
d24596d5 | 65 | returns, the current value of the SPU program counter is written to |
f9f7c042 | 66 | .IR npc , |
d24596d5 | 67 | so successive calls to |
f9f7c042 | 68 | .BR spu_run () |
d24596d5 MK |
69 | can use the same |
70 | .I npc | |
71 | pointer. | |
efeece04 | 72 | .PP |
d24596d5 | 73 | The |
f9f7c042 | 74 | .I event |
d24596d5 MK |
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 | |
f9f7c042 | 80 | .BR spu_run () |
d24596d5 | 81 | returns. |
efeece04 | 82 | .PP |
d24596d5 | 83 | The status code may be one (or more) of the following constants: |
f9f7c042 MK |
84 | .TP |
85 | .B SPE_EVENT_DMA_ALIGNMENT | |
d24596d5 | 86 | A DMA alignment error occurred. |
f9f7c042 MK |
87 | .TP |
88 | .B SPE_EVENT_INVALID_DMA | |
d24596d5 | 89 | An invalid MFC DMA command was attempted. |
f9f7c042 MK |
90 | .TP |
91 | .B SPE_EVENT_SPE_DATA_STORAGE | |
d24596d5 | 92 | A DMA storage error occurred. |
f9f7c042 MK |
93 | .TP |
94 | .B SPE_EVENT_SPE_ERROR | |
d24596d5 | 95 | An illegal instruction was executed. |
f9f7c042 | 96 | .PP |
d24596d5 MK |
97 | NULL |
98 | is a valid value for the | |
f9f7c042 | 99 | .I event |
d24596d5 MK |
100 | argument. |
101 | In this case, the events will not be reported to the calling process. | |
f9f7c042 | 102 | .SH RETURN VALUE |
d24596d5 | 103 | On success, |
f9f7c042 MK |
104 | .BR spu_run () |
105 | returns the value of the | |
106 | .I spu_status | |
107 | register. | |
dec985f9 | 108 | On error, it returns \-1 and sets |
f9f7c042 MK |
109 | .I errno |
110 | to one of the error codes listed below. | |
efeece04 | 111 | .PP |
e0bf9127 | 112 | The |
f9f7c042 MK |
113 | .I spu_status |
114 | register value is a bit mask of status codes and | |
d24596d5 MK |
115 | optionally a 14-bit code returned from the |
116 | .BR stop-and-signal | |
f9f7c042 MK |
117 | instruction on the SPU. |
118 | The bit masks for the status codes | |
119 | are: | |
120 | .TP | |
121 | .B 0x02 | |
d24596d5 MK |
122 | SPU was stopped by a |
123 | .BR stop-and-signal | |
124 | instruction. | |
f9f7c042 MK |
125 | .TP |
126 | .B 0x04 | |
d24596d5 MK |
127 | SPU was stopped by a |
128 | .BR halt | |
129 | instruction. | |
f9f7c042 MK |
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. | |
d24596d5 MK |
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. | |
33a0ccb2 | 147 | These bits are valid only if the 0x02 bit is set. |
f9f7c042 MK |
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 | |
f9f7c042 MK |
155 | .B EBADF |
156 | .I fd | |
157 | is not a valid file descriptor. | |
158 | .TP | |
159 | .B EFAULT | |
160 | .I npc | |
d24596d5 MK |
161 | is not a valid pointer, or |
162 | .I event | |
163 | is non-NULL and an invalid pointer. | |
f9f7c042 MK |
164 | .TP |
165 | .B EINTR | |
166 | A signal occurred while | |
167 | .BR spu_run () | |
76e533c4 MK |
168 | was in progress; see |
169 | .BR signal (7). | |
f9f7c042 MK |
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 | |
d24596d5 | 177 | is not a valid file descriptor returned from |
f9f7c042 MK |
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 | |
2777b1ca | 190 | .BR spu_run () |
f9f7c042 MK |
191 | system call was added to Linux in kernel 2.6.16. |
192 | .SH CONFORMING TO | |
33a0ccb2 | 193 | This call is Linux-specific and implemented only by the PowerPC |
f9f7c042 MK |
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. | |
e0bf9127 | 203 | See |
608bf950 SK |
204 | .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ |
205 | .UE | |
f9f7c042 | 206 | for the recommended libraries. |
d24596d5 MK |
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. | |
efeece04 | 212 | .PP |
408731d4 | 213 | .EX |
d24596d5 MK |
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 | ||
d1a71985 | 221 | #define handle_error(msg) \e |
d24596d5 MK |
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); | |
c3074d70 | 230 | if (context == \-1) |
d24596d5 MK |
231 | handle_error("spu_create"); |
232 | ||
f81fb444 | 233 | /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs |
d24596d5 MK |
234 | * local store memory |
235 | */ | |
236 | instruction = 0x00001234; | |
237 | ||
238 | fd = open("/spu/example\-context/mem", O_RDWR); | |
c3074d70 | 239 | if (fd == \-1) |
d24596d5 MK |
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); | |
c3074d70 | 250 | if (spu_status == \-1) |
d24596d5 MK |
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 | */ | |
d1a71985 | 257 | printf("SPU Status: 0x%08x\en", spu_status); |
d24596d5 MK |
258 | |
259 | exit(EXIT_SUCCESS); | |
260 | } | |
408731d4 | 261 | .EE |
d24596d5 MK |
262 | .\" .SH AUTHORS |
263 | .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org> | |
f9f7c042 MK |
264 | .SH SEE ALSO |
265 | .BR close (2), | |
266 | .BR spu_create (2), | |
d24596d5 | 267 | .BR capabilities (7), |
f9f7c042 | 268 | .BR spufs (7) |