]>
Commit | Line | Data |
---|---|---|
d24596d5 | 1 | .\" Copyright (c) International Business Machines Corp., 2006 |
f9f7c042 | 2 | .\" |
d24596d5 | 3 | .\" This program is free software; you can redistribute it and/or |
f9f7c042 MK |
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, | |
d24596d5 MK |
9 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | |
f9f7c042 MK |
11 | .\" the GNU General Public License for more details. |
12 | .\" | |
13 | .\" You should have received a copy of the GNU General Public License | |
d24596d5 | 14 | .\" along with this program; if not, write to the Free Software |
f9f7c042 MK |
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 | |
d24596d5 MK |
22 | .\" 2007-09-28, updates for newer kernels, added example |
23 | .\" by Jeremy Kerr <jk@ozlabs.org> | |
f9f7c042 | 24 | .\" |
d24596d5 | 25 | .TH SPU_RUN 2 2007-11-25 Linux "Linux Programmer's Manual" |
f9f7c042 MK |
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 | |
e0bf9127 | 36 | The |
f9f7c042 | 37 | .BR spu_run () |
e0bf9127 MK |
38 | system call is used on PowerPC machines that implement the |
39 | Cell Broadband Engine Architecture in order to access Synergistic | |
f9f7c042 MK |
40 | Processor Units (SPUs). |
41 | The | |
42 | .I fd | |
e0bf9127 | 43 | argument is a file descriptor returned by |
f9f7c042 | 44 | .BR spu_create (2) |
d24596d5 MK |
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 | |
f9f7c042 MK |
48 | .IR npc . |
49 | ||
e0bf9127 | 50 | Execution of SPU code happens synchronously, meaning that |
f9f7c042 | 51 | .BR spu_run () |
d24596d5 | 52 | blocks while the SPU is still running. |
f9f7c042 | 53 | If there is a need |
e0bf9127 | 54 | to execute SPU code in parallel with other code on either the |
f9f7c042 | 55 | main CPU or other SPUs, a new thread of execution must be created |
d24596d5 MK |
56 | first (e.g., using |
57 | .BR pthread_create (3)). | |
f9f7c042 MK |
58 | |
59 | When | |
60 | .BR spu_run () | |
d24596d5 | 61 | returns, the current value of the SPU program counter is written to |
f9f7c042 | 62 | .IR npc , |
d24596d5 | 63 | so successive calls to |
f9f7c042 | 64 | .BR spu_run () |
d24596d5 MK |
65 | can use the same |
66 | .I npc | |
67 | pointer. | |
f9f7c042 | 68 | |
d24596d5 | 69 | The |
f9f7c042 | 70 | .I event |
d24596d5 MK |
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 | |
f9f7c042 | 76 | .BR spu_run () |
d24596d5 MK |
77 | returns. |
78 | ||
79 | The status code may be one (or more) of the following constants: | |
f9f7c042 MK |
80 | .TP |
81 | .B SPE_EVENT_DMA_ALIGNMENT | |
d24596d5 | 82 | A DMA alignment error occurred. |
f9f7c042 MK |
83 | .TP |
84 | .B SPE_EVENT_INVALID_DMA | |
d24596d5 | 85 | An invalid MFC DMA command was attempted. |
f9f7c042 MK |
86 | .TP |
87 | .B SPE_EVENT_SPE_DATA_STORAGE | |
d24596d5 | 88 | A DMA storage error occurred. |
f9f7c042 MK |
89 | .TP |
90 | .B SPE_EVENT_SPE_ERROR | |
d24596d5 | 91 | An illegal instruction was executed. |
f9f7c042 | 92 | .PP |
d24596d5 MK |
93 | NULL |
94 | is a valid value for the | |
f9f7c042 | 95 | .I event |
d24596d5 MK |
96 | argument. |
97 | In this case, the events will not be reported to the calling process. | |
f9f7c042 | 98 | .SH RETURN VALUE |
d24596d5 | 99 | On success, |
f9f7c042 MK |
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. | |
d24596d5 | 107 | |
e0bf9127 | 108 | The |
f9f7c042 MK |
109 | .I spu_status |
110 | register value is a bit mask of status codes and | |
d24596d5 MK |
111 | optionally a 14-bit code returned from the |
112 | .BR stop-and-signal | |
f9f7c042 MK |
113 | instruction on the SPU. |
114 | The bit masks for the status codes | |
115 | are: | |
116 | .TP | |
117 | .B 0x02 | |
d24596d5 MK |
118 | SPU was stopped by a |
119 | .BR stop-and-signal | |
120 | instruction. | |
f9f7c042 MK |
121 | .TP |
122 | .B 0x04 | |
d24596d5 MK |
123 | SPU was stopped by a |
124 | .BR halt | |
125 | instruction. | |
f9f7c042 MK |
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. | |
d24596d5 MK |
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. | |
f9f7c042 MK |
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 | |
f9f7c042 MK |
151 | .B EBADF |
152 | .I fd | |
153 | is not a valid file descriptor. | |
154 | .TP | |
155 | .B EFAULT | |
156 | .I npc | |
d24596d5 MK |
157 | is not a valid pointer, or |
158 | .I event | |
159 | is non-NULL and an invalid pointer. | |
f9f7c042 MK |
160 | .TP |
161 | .B EINTR | |
162 | A signal occurred while | |
163 | .BR spu_run () | |
164 | was in progress. | |
165 | The | |
166 | .I npc | |
167 | value has been updated to the new program counter value if | |
168 | necessary. | |
169 | .TP | |
170 | .B EINVAL | |
171 | .I fd | |
d24596d5 | 172 | is not a valid file descriptor returned from |
f9f7c042 MK |
173 | .BR spu_create (2). |
174 | .TP | |
175 | .B ENOMEM | |
176 | There was not enough memory available to handle a page fault | |
177 | resulting from a Memory Flow Controller (MFC) direct memory access. | |
178 | .TP | |
179 | .B ENOSYS | |
180 | The functionality is not provided by the current system, because | |
181 | either the hardware does not provide SPUs or the spufs module is not | |
182 | loaded. | |
183 | .SH VERSIONS | |
184 | The | |
2777b1ca | 185 | .BR spu_run () |
f9f7c042 MK |
186 | system call was added to Linux in kernel 2.6.16. |
187 | .SH CONFORMING TO | |
8382f16d | 188 | This call is Linux-specific and only implemented by the PowerPC |
f9f7c042 MK |
189 | architecture. |
190 | Programs using this system call are not portable. | |
191 | .SH NOTES | |
192 | Glibc does not provide a wrapper for this system call; call it using | |
193 | .BR syscall (2). | |
194 | Note however, that | |
195 | .BR spu_run () | |
196 | is meant to be used from libraries that implement a more abstract | |
197 | interface to SPUs, not to be used from regular applications. | |
e0bf9127 | 198 | See |
f9f7c042 MK |
199 | .I http://www.bsc.es/projects/deepcomputing/linuxoncell/ |
200 | for the recommended libraries. | |
d24596d5 MK |
201 | .SH EXAMPLE |
202 | The following is an example of running a simple, one-instruction SPU | |
203 | program with the | |
204 | .BR spu_run () | |
205 | system call. | |
206 | ||
207 | .nf | |
208 | #include <stdlib.h> | |
209 | #include <stdint.h> | |
210 | #include <unistd.h> | |
211 | #include <stdio.h> | |
212 | #include <sys/types.h> | |
213 | #include <fcntl.h> | |
214 | ||
215 | #define handle_error(msg) \\ | |
216 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
217 | ||
218 | int main(void) | |
219 | { | |
220 | int context, fd, spu_status; | |
221 | uint32_t instruction, npc; | |
222 | ||
223 | context = spu_create("/spu/example\-context", 0, 0755); | |
224 | if (context == -1) | |
225 | handle_error("spu_create"); | |
226 | ||
227 | /* write a 'stop 0x1234' instruction to the SPU's | |
228 | * local store memory | |
229 | */ | |
230 | instruction = 0x00001234; | |
231 | ||
232 | fd = open("/spu/example\-context/mem", O_RDWR); | |
233 | if (fd == -1) | |
234 | handle_error("open"); | |
235 | write(fd, &instruction, sizeof(instruction)); | |
236 | ||
237 | /* set npc to the starting instruction address of the | |
238 | * SPU program. Since we wrote the instruction at the | |
239 | * start of the mem file, the entry point will be 0x0 | |
240 | */ | |
241 | npc = 0; | |
242 | ||
243 | spu_status = spu_run(context, &npc, NULL); | |
244 | if (spu_status == -1) | |
245 | handle_error("open"); | |
246 | ||
247 | /* we should see a status code of 0x1234002: | |
248 | * 0x00000002 (spu was stopped due to stop\-and\-signal) | |
249 | * | 0x12340000 (the stop\-and\-signal code) | |
250 | */ | |
251 | printf("SPU Status: 0x%08x\\n", spu_status); | |
252 | ||
253 | exit(EXIT_SUCCESS); | |
254 | } | |
255 | .fi | |
256 | .\" .SH AUTHORS | |
257 | .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org> | |
f9f7c042 MK |
258 | .SH SEE ALSO |
259 | .BR close (2), | |
260 | .BR spu_create (2), | |
d24596d5 | 261 | .BR capabilities (7), |
f9f7c042 | 262 | .BR spufs (7) |