]>
Commit | Line | Data |
---|---|---|
4875e482 | 1 | .\" Copyright (c) International Business Machines Corp., 2006 |
6282f7bd | 2 | .\" |
e4a74ca8 | 3 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
6282f7bd MK |
4 | .\" |
5 | .\" HISTORY: | |
6 | .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>, | |
7 | .\" Mark Nutter <mnutter@us.ibm.com> and | |
8 | .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com> | |
9 | .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com> | |
10 | .\" 2007-07-10, quite a lot of polishing by mtk | |
4875e482 | 11 | .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> |
6282f7bd | 12 | .\" |
4c1c5274 | 13 | .TH spufs 7 (date) "Linux man-pages (unreleased)" |
6282f7bd | 14 | .SH NAME |
9ee4a2b6 | 15 | spufs \- SPU filesystem |
6282f7bd | 16 | .SH DESCRIPTION |
9ee4a2b6 | 17 | The SPU filesystem is used on PowerPC machines that implement the |
6282f7bd MK |
18 | Cell Broadband Engine Architecture in order to access Synergistic |
19 | Processor Units (SPUs). | |
c6d039a3 | 20 | .P |
9ee4a2b6 | 21 | The filesystem provides a name space similar to POSIX shared |
6282f7bd MK |
22 | memory or message queues. |
23 | Users that have write permissions | |
9ee4a2b6 | 24 | on the filesystem can use |
6282f7bd | 25 | .BR spu_create (2) |
66516789 MK |
26 | to establish SPU contexts under the |
27 | .B spufs | |
28 | root directory. | |
c6d039a3 | 29 | .P |
6282f7bd MK |
30 | Every SPU context is represented by a directory containing |
31 | a predefined set of files. | |
32 | These files can be | |
33 | used for manipulating the state of the logical SPU. | |
4875e482 | 34 | Users can change permissions on the files, but can't |
6282f7bd | 35 | add or remove files. |
c634028a | 36 | .SS Mount options |
6282f7bd MK |
37 | .TP |
38 | .B uid=<uid> | |
4875e482 | 39 | Set the user owning the mount point; the default is 0 (root). |
6282f7bd MK |
40 | .TP |
41 | .B gid=<gid> | |
4875e482 MK |
42 | Set the group owning the mount point; the default is 0 (root). |
43 | .TP | |
44 | .B mode=<mode> | |
66516789 MK |
45 | Set the mode of the top-level directory in |
46 | .BR spufs , | |
4875e482 MK |
47 | as an octal mode string. |
48 | The default is 0775. | |
6282f7bd MK |
49 | .SS Files |
50 | The files in | |
66516789 | 51 | .B spufs |
6282f7bd MK |
52 | mostly follow the standard behavior for regular system calls like |
53 | .BR read (2) | |
54 | or | |
55 | .BR write (2), | |
56 | but often support only a subset of the operations | |
9ee4a2b6 | 57 | supported on regular filesystems. |
6282f7bd MK |
58 | This list details the supported |
59 | operations and the deviations from the standard behavior described | |
60 | in the respective man pages. | |
c6d039a3 | 61 | .P |
6282f7bd MK |
62 | All files that support the |
63 | .BR read (2) | |
64 | operation also support | |
65 | .BR readv (2) | |
66 | and all files that support the | |
67 | .BR write (2) | |
68 | operation also support | |
69 | .BR writev (2). | |
6282f7bd MK |
70 | All files support the |
71 | .BR access (2) | |
72 | and | |
73 | .BR stat (2) | |
74 | family of operations, but for the latter call, | |
e0bf9127 | 75 | the only fields of the returned |
6282f7bd MK |
76 | .I stat |
77 | structure that contain reliable information are | |
78 | .IR st_mode , | |
79 | .IR st_nlink , | |
80 | .IR st_uid , | |
81 | and | |
82 | .IR st_gid . | |
c6d039a3 | 83 | .P |
6282f7bd | 84 | All files support the |
998e8717 AC |
85 | .BR chmod (2)/\c |
86 | .BR fchmod (2) | |
6282f7bd | 87 | and |
998e8717 AC |
88 | .BR chown (2)/\c |
89 | .BR fchown (2) | |
6282f7bd MK |
90 | operations, but will not be able to grant permissions that contradict |
91 | the possible operations (e.g., read access on the | |
92 | .I wbox | |
93 | file). | |
c6d039a3 | 94 | .P |
6282f7bd MK |
95 | The current set of files is: |
96 | .TP | |
4875e482 MK |
97 | .I /capabilities |
98 | Contains a comma-delimited string representing the capabilities of this | |
99 | SPU context. | |
100 | Possible capabilities are: | |
101 | .RS | |
102 | .TP | |
103 | .B sched | |
104 | This context may be scheduled. | |
105 | .TP | |
106 | .B step | |
107 | This context can be run in single-step mode, for debugging. | |
c6d039a3 | 108 | .P |
4875e482 MK |
109 | New capabilities flags may be added in the future. |
110 | .RE | |
111 | .TP | |
112 | .I /mem | |
6282f7bd MK |
113 | the contents of the local storage memory of the SPU. |
114 | This can be accessed like a regular shared memory | |
115 | file and contains both code and data in the address | |
116 | space of the SPU. | |
117 | The possible operations on an open | |
118 | .I mem | |
119 | file are: | |
120 | .RS | |
121 | .TP | |
6fdb1c03 AC |
122 | .BR read (2) |
123 | .TQ | |
124 | .BR pread (2) | |
125 | .TQ | |
126 | .BR write (2) | |
127 | .TQ | |
128 | .BR pwrite (2) | |
129 | .TQ | |
130 | .BR lseek (2) | |
e0bf9127 | 131 | These operate as usual, with the exception that |
4875e482 MK |
132 | .BR lseek (2), |
133 | .BR write (2), | |
e0bf9127 | 134 | and |
6282f7bd MK |
135 | .BR pwrite (2) |
136 | are not supported beyond the end of the file. | |
137 | The file size | |
138 | is the size of the local storage of the SPU, | |
139 | which is normally 256 kilobytes. | |
140 | .TP | |
141 | .BR mmap (2) | |
142 | Mapping | |
143 | .I mem | |
144 | into the process address space provides access to the SPU local | |
145 | storage within the process address space. | |
146 | Only | |
147 | .B MAP_SHARED | |
148 | mappings are allowed. | |
149 | .RE | |
150 | .TP | |
4875e482 MK |
151 | .I /regs |
152 | Contains the saved general-purpose registers of the SPU context. | |
153 | This file contains the 128-bit values of each register, | |
154 | from register 0 to register 127, in order. | |
155 | This allows the general-purpose registers to be | |
156 | inspected for debugging. | |
a721e8b2 | 157 | .IP |
4875e482 MK |
158 | Reading to or writing from this file requires that the context is |
159 | scheduled out, so use of this file is not recommended in normal | |
160 | program operation. | |
a721e8b2 | 161 | .IP |
4875e482 MK |
162 | The |
163 | .I regs | |
164 | file is not present on contexts that have been created with the | |
165 | .B SPU_CREATE_NOSCHED | |
166 | flag. | |
4875e482 MK |
167 | .TP |
168 | .I /mbox | |
6282f7bd | 169 | The first SPU-to-CPU communication mailbox. |
4875e482 | 170 | This file is read-only and can be read in units of 4 bytes. |
33a0ccb2 | 171 | The file can be used only in nonblocking mode \- even |
6282f7bd | 172 | .BR poll (2) |
4875e482 | 173 | cannot be used to block on this file. |
e0bf9127 | 174 | The only possible operation on an open |
6282f7bd MK |
175 | .I mbox |
176 | file is: | |
177 | .RS | |
178 | .TP | |
179 | .BR read (2) | |
180 | If | |
181 | .I count | |
182 | is smaller than four, | |
183 | .BR read (2) | |
184 | returns \-1 and sets | |
185 | .I errno | |
186 | to | |
187 | .BR EINVAL . | |
4875e482 MK |
188 | If there is no data available in the mailbox (i.e., the SPU has not |
189 | sent a mailbox message), the return value is set to \-1 and | |
6282f7bd MK |
190 | .I errno |
191 | is set to | |
192 | .BR EAGAIN . | |
193 | When data | |
194 | has been read successfully, four bytes are placed in | |
195 | the data buffer and the value four is returned. | |
196 | .RE | |
197 | .TP | |
4875e482 | 198 | .I /ibox |
6282f7bd MK |
199 | The second SPU-to-CPU communication mailbox. |
200 | This file is similar to the first mailbox file, but can be read | |
a612f2d0 MK |
201 | in blocking I/O mode, thus calling |
202 | .BR read (2) | |
203 | on an open | |
204 | .I ibox | |
205 | file will block until the SPU has written data to its interrupt mailbox | |
206 | channel (unless the file has been opened with | |
207 | .BR O_NONBLOCK , | |
208 | see below). | |
209 | Also, | |
6282f7bd | 210 | .BR poll (2) |
a612f2d0 MK |
211 | and similar system calls can be used to monitor for the presence |
212 | of mailbox data. | |
a721e8b2 | 213 | .IP |
e0bf9127 | 214 | The possible operations on an open |
6282f7bd MK |
215 | .I ibox |
216 | file are: | |
217 | .RS | |
218 | .TP | |
219 | .BR read (2) | |
220 | If | |
221 | .I count | |
222 | is smaller than four, | |
223 | .BR read (2) | |
224 | returns \-1 and sets | |
225 | .I errno | |
226 | to | |
227 | .BR EINVAL . | |
228 | If there is no data available in the mailbox and the file | |
229 | descriptor has been opened with | |
230 | .BR O_NONBLOCK , | |
231 | the return value is set to \-1 and | |
232 | .I errno | |
233 | is set to | |
234 | .BR EAGAIN . | |
a721e8b2 | 235 | .IP |
6282f7bd MK |
236 | If there is no data available in the mailbox and the file |
237 | descriptor has been opened without | |
238 | .BR O_NONBLOCK , | |
239 | the call will | |
240 | block until the SPU writes to its interrupt mailbox channel. | |
241 | When data has been read successfully, four bytes are placed in | |
242 | the data buffer and the value four is returned. | |
243 | .TP | |
244 | .BR poll (2) | |
e0bf9127 | 245 | Poll on the |
6282f7bd MK |
246 | .I ibox |
247 | file returns | |
248 | .I "(POLLIN | POLLRDNORM)" | |
249 | whenever data is available for reading. | |
250 | .RE | |
251 | .TP | |
4875e482 | 252 | .I /wbox |
6282f7bd | 253 | The CPU-to-SPU communication mailbox. |
4875e482 | 254 | It is write-only and can be written in units of four bytes. |
6282f7bd MK |
255 | If the mailbox is full, |
256 | .BR write (2) | |
4875e482 | 257 | will block, and |
6282f7bd | 258 | .BR poll (2) |
4875e482 | 259 | can be used to block until the mailbox is available for writing again. |
e0bf9127 | 260 | The possible operations on an open |
6282f7bd MK |
261 | .I wbox |
262 | file are: | |
263 | .RS | |
264 | .TP | |
265 | .BR write (2) | |
266 | If | |
267 | .I count | |
268 | is smaller than four, | |
269 | .BR write (2) | |
270 | returns \-1 and sets | |
271 | .I errno | |
272 | to | |
273 | .BR EINVAL . | |
274 | If there is no space available in the mailbox and the file | |
275 | descriptor has been opened with | |
276 | .BR O_NONBLOCK , | |
277 | the return | |
278 | value is set to \-1 and | |
279 | .I errno | |
280 | is set to | |
281 | .BR EAGAIN . | |
a721e8b2 | 282 | .IP |
6282f7bd MK |
283 | If there is no space available in the mailbox and the file |
284 | descriptor has been opened without | |
285 | .BR O_NONBLOCK , | |
b2ca3ebe | 286 | the call will block until the SPU reads from its |
4875e482 MK |
287 | PPE (PowerPC Processing Element) |
288 | mailbox channel. | |
e0bf9127 | 289 | When data has been written successfully, |
6282f7bd MK |
290 | the system call returns four as its function result. |
291 | .TP | |
292 | .BR poll (2) | |
e0bf9127 | 293 | A poll on the |
6282f7bd MK |
294 | .I wbox |
295 | file returns | |
296 | .I "(POLLOUT | POLLWRNORM)" | |
297 | whenever space is available for writing. | |
298 | .RE | |
299 | .TP | |
6fdb1c03 AC |
300 | .I /mbox_stat |
301 | .TQ | |
302 | .I /ibox_stat | |
303 | .TQ | |
304 | .I /wbox_stat | |
6282f7bd | 305 | These are read-only files that contain the length of the current |
36546c38 | 306 | queue of each mailbox\[em]that is, how many words can be read from |
6282f7bd MK |
307 | .IR mbox " or " ibox |
308 | or how many words can be written to | |
e0bf9127 | 309 | .I wbox |
6282f7bd MK |
310 | without blocking. |
311 | The files can be read only in four-byte units and return | |
312 | a big-endian binary integer number. | |
4875e482 | 313 | The only possible operation on an open |
6282f7bd | 314 | .I *box_stat |
4875e482 | 315 | file is: |
6282f7bd MK |
316 | .RS |
317 | .TP | |
318 | .BR read (2) | |
319 | If | |
320 | .I count | |
321 | is smaller than four, | |
322 | .BR read (2) | |
323 | returns \-1 and sets | |
324 | .I errno | |
325 | to | |
c7992edc | 326 | .BR EINVAL . |
6282f7bd MK |
327 | Otherwise, a four-byte value is placed in the data buffer. |
328 | This value is the number of elements that can be read from (for | |
1ae6b2c7 | 329 | .I mbox_stat |
6282f7bd MK |
330 | and |
331 | .IR ibox_stat ) | |
332 | or written to (for | |
333 | .IR wbox_stat ) | |
4875e482 | 334 | the respective mailbox without blocking or returning an |
1ae6b2c7 | 335 | .B EAGAIN |
6282f7bd MK |
336 | error. |
337 | .RE | |
338 | .TP | |
6fdb1c03 AC |
339 | .I /npc |
340 | .TQ | |
341 | .I /decr | |
342 | .TQ | |
343 | .I /decr_status | |
344 | .TQ | |
345 | .I /spu_tag_mask | |
346 | .TQ | |
347 | .I /event_mask | |
348 | .TQ | |
349 | .I /event_status | |
350 | .TQ | |
351 | .I /srr0 | |
352 | .TQ | |
353 | .I /lslr | |
4875e482 MK |
354 | Internal registers of the SPU. |
355 | These files contain an ASCII string | |
356 | representing the hex value of the specified register. | |
357 | Reads and writes on these | |
358 | files (except for | |
359 | .IR npc , | |
360 | see below) require that the SPU context be scheduled out, | |
361 | so frequent access to | |
362 | these files is not recommended for normal program operation. | |
6282f7bd MK |
363 | .IP |
364 | The contents of these files are: | |
365 | .RS | |
366 | .TP 16 | |
367 | .I npc | |
33a0ccb2 | 368 | Next Program Counter \- valid only when the SPU is in a stopped state. |
6282f7bd MK |
369 | .TP |
370 | .I decr | |
371 | SPU Decrementer | |
372 | .TP | |
373 | .I decr_status | |
374 | Decrementer Status | |
375 | .TP | |
376 | .I spu_tag_mask | |
377 | MFC tag mask for SPU DMA | |
378 | .TP | |
379 | .I event_mask | |
380 | Event mask for SPU interrupts | |
381 | .TP | |
4875e482 MK |
382 | .I event_status |
383 | Number of SPU events pending (read-only) | |
384 | .TP | |
6282f7bd MK |
385 | .I srr0 |
386 | Interrupt Return address register | |
4875e482 MK |
387 | .TP |
388 | .I lslr | |
389 | Local Store Limit Register | |
6282f7bd MK |
390 | .RE |
391 | .IP | |
4875e482 | 392 | The possible operations on these files are: |
6282f7bd MK |
393 | .RS |
394 | .TP | |
395 | .BR read (2) | |
4875e482 MK |
396 | Reads the current register value. |
397 | If the register value is larger than the buffer passed to the | |
6282f7bd | 398 | .BR read (2) |
4875e482 MK |
399 | system call, subsequent reads will continue reading from the same |
400 | buffer, until the end of the buffer is reached. | |
a721e8b2 | 401 | .IP |
6282f7bd | 402 | When a complete string has been read, all subsequent read operations |
e0bf9127 | 403 | will return zero bytes and a new file descriptor needs to be opened |
6282f7bd MK |
404 | to read a new value. |
405 | .TP | |
406 | .BR write (2) | |
e0bf9127 | 407 | A |
6282f7bd | 408 | .BR write (2) |
e0bf9127 | 409 | operation on the file sets the register to the |
6282f7bd | 410 | value given in the string. |
e0bf9127 | 411 | The string is parsed from the beginning |
80c9146c | 412 | until the first nonnumeric character or the end of the buffer. |
e0bf9127 | 413 | Subsequent writes to the same file descriptor overwrite the |
6282f7bd | 414 | previous setting. |
a721e8b2 | 415 | .IP |
4875e482 MK |
416 | Except for the |
417 | .I npc | |
418 | file, these files are not present on contexts that have been created with | |
419 | the | |
420 | .B SPU_CREATE_NOSCHED | |
421 | flag. | |
6282f7bd MK |
422 | .RE |
423 | .TP | |
1ae6b2c7 | 424 | .I /fpcr |
e0bf9127 | 425 | This file provides access to the Floating Point Status and |
4875e482 MK |
426 | Control Register (fcpr) as a binary, four-byte file. |
427 | The operations on the | |
6282f7bd MK |
428 | .I fpcr |
429 | file are: | |
430 | .RS | |
431 | .TP | |
432 | .BR read (2) | |
433 | If | |
434 | .I count | |
435 | is smaller than four, | |
436 | .BR read (2) | |
437 | returns \-1 and sets | |
438 | .I errno | |
439 | to | |
440 | .BR EINVAL . | |
441 | Otherwise, a four-byte value is placed in the data buffer; | |
442 | this is the current value of the | |
443 | .I fpcr | |
444 | register. | |
445 | .TP | |
446 | .BR write (2) | |
447 | If | |
448 | .I count | |
449 | is smaller than four, | |
450 | .BR write (2) | |
451 | returns \-1 and sets | |
452 | .I errno | |
453 | to | |
454 | .BR EINVAL . | |
455 | Otherwise, a four-byte value is copied from the data buffer, | |
456 | updating the value of the | |
457 | .I fpcr | |
458 | register. | |
459 | .RE | |
460 | .TP | |
6fdb1c03 AC |
461 | .I /signal1 |
462 | .TQ | |
463 | .I /signal2 | |
6282f7bd MK |
464 | The files provide access to the two signal notification channels |
465 | of an SPU. | |
4875e482 | 466 | These are read-write files that operate on four-byte words. |
6282f7bd MK |
467 | Writing to one of these files triggers an interrupt on the SPU. |
468 | The value written to the signal files can | |
469 | be read from the SPU through a channel read or from | |
470 | host user space through the file. | |
471 | After the value has been read by the SPU, it is reset to zero. | |
e0bf9127 | 472 | The possible operations on an open |
6282f7bd MK |
473 | .I signal1 |
474 | or | |
475 | .I signal2 | |
476 | file are: | |
477 | .RS | |
478 | .TP | |
479 | .BR read (2) | |
480 | If | |
481 | .I count | |
482 | is smaller than four, | |
483 | .BR read (2) | |
484 | returns \-1 and sets | |
485 | .I errno | |
486 | to | |
487 | .BR EINVAL . | |
488 | Otherwise, a four-byte value is placed in the data buffer; | |
489 | this is the current value of the specified signal notification | |
490 | register. | |
491 | .TP | |
492 | .BR write (2) | |
493 | If | |
494 | .I count | |
495 | is smaller than four, | |
496 | .BR write (2) | |
497 | returns \-1 and sets | |
498 | .I errno | |
499 | to | |
500 | .BR EINVAL . | |
501 | Otherwise, a four-byte value is copied from the data buffer, | |
e0bf9127 | 502 | updating the value of the specified signal notification |
6282f7bd | 503 | register. |
e0bf9127 MK |
504 | The signal notification register will either be replaced with |
505 | the input data or will be updated to the bitwise OR operation | |
6282f7bd MK |
506 | of the old value and the input data, depending on the contents |
507 | of the | |
1ae6b2c7 | 508 | .I signal1_type |
6282f7bd | 509 | or |
1ae6b2c7 | 510 | .I signal2_type |
6282f7bd MK |
511 | files respectively. |
512 | .RE | |
513 | .TP | |
6fdb1c03 AC |
514 | .I /signal1_type |
515 | .TQ | |
516 | .I /signal2_type | |
6282f7bd | 517 | These two files change the behavior of the |
1ae6b2c7 | 518 | .I signal1 |
6282f7bd | 519 | and |
1ae6b2c7 | 520 | .I signal2 |
6282f7bd | 521 | notification files. |
4875e482 MK |
522 | They contain a numeric ASCII string which is read |
523 | as either "1" or "0". | |
6282f7bd MK |
524 | In mode 0 (overwrite), the hardware replaces the contents |
525 | of the signal channel with the data that is written to it. | |
526 | In mode 1 (logical OR), the hardware accumulates the bits | |
527 | that are subsequently written to it. | |
e0bf9127 | 528 | The possible operations on an open |
6282f7bd MK |
529 | .I signal1_type |
530 | or | |
531 | .I signal2_type | |
532 | file are: | |
533 | .RS | |
534 | .TP | |
535 | .BR read (2) | |
536 | When the count supplied to the | |
537 | .BR read (2) | |
4875e482 MK |
538 | call is shorter than the required length for the digit (plus a newline |
539 | character), subsequent reads from the same file descriptor will | |
540 | complete the string. | |
6282f7bd MK |
541 | When a complete string has been read, all subsequent read operations |
542 | will return zero bytes and a new file descriptor needs to be opened | |
543 | to read the value again. | |
544 | .TP | |
545 | .BR write (2) | |
e0bf9127 | 546 | A |
6282f7bd MK |
547 | .BR write (2) |
548 | operation on the file sets the register to the | |
549 | value given in the string. | |
550 | The string is parsed from the beginning | |
80c9146c | 551 | until the first nonnumeric character or the end of the buffer. |
6282f7bd MK |
552 | Subsequent writes to the same file descriptor overwrite the |
553 | previous setting. | |
554 | .RE | |
4875e482 | 555 | .TP |
6fdb1c03 AC |
556 | .I /mbox_info |
557 | .TQ | |
558 | .I /ibox_info | |
559 | .TQ | |
560 | .I /wbox_info | |
561 | .TQ | |
562 | .I /dma_into | |
563 | .TQ | |
564 | .I /proxydma_info | |
4875e482 MK |
565 | Read-only files that contain the saved state of the SPU mailboxes and |
566 | DMA queues. | |
567 | This allows the SPU status to be inspected, mainly for debugging. | |
568 | The | |
569 | .I mbox_info | |
570 | and | |
571 | .I ibox_info | |
572 | files each contain the four-byte mailbox message that has been written | |
573 | by the SPU. | |
574 | If no message has been written to these mailboxes, then | |
575 | contents of these files is undefined. | |
576 | The | |
577 | .IR mbox_stat , | |
d556548b | 578 | .IR ibox_stat , |
4875e482 MK |
579 | and |
580 | .I wbox_stat | |
581 | files contain the available message count. | |
a721e8b2 | 582 | .IP |
4875e482 MK |
583 | The |
584 | .I wbox_info | |
585 | file contains an array of four-byte mailbox messages, which have been | |
586 | sent to the SPU. | |
587 | With current CBEA machines, the array is four items in | |
588 | length, so up to 4 * 4 = 16 bytes can be read from this file. | |
589 | If any mailbox queue entry is empty, | |
590 | then the bytes read at the corresponding location are undefined. | |
a721e8b2 | 591 | .IP |
4875e482 MK |
592 | The |
593 | .I dma_info | |
594 | file contains the contents of the SPU MFC DMA queue, represented as the | |
595 | following structure: | |
a721e8b2 | 596 | .IP |
088a639b | 597 | .in +4n |
b8302363 | 598 | .EX |
4875e482 MK |
599 | struct spu_dma_info { |
600 | uint64_t dma_info_type; | |
601 | uint64_t dma_info_mask; | |
602 | uint64_t dma_info_status; | |
603 | uint64_t dma_info_stall_and_notify; | |
604 | uint64_t dma_info_atomic_command_status; | |
605 | struct mfc_cq_sr dma_info_command_data[16]; | |
606 | }; | |
b8302363 | 607 | .EE |
4875e482 | 608 | .in |
a721e8b2 | 609 | .IP |
4875e482 MK |
610 | The last member of this data structure is the actual DMA queue, |
611 | containing 16 entries. | |
612 | The | |
613 | .I mfc_cq_sr | |
614 | structure is defined as: | |
a721e8b2 | 615 | .IP |
088a639b | 616 | .in +4n |
b8302363 | 617 | .EX |
4875e482 MK |
618 | struct mfc_cq_sr { |
619 | uint64_t mfc_cq_data0_RW; | |
620 | uint64_t mfc_cq_data1_RW; | |
621 | uint64_t mfc_cq_data2_RW; | |
622 | uint64_t mfc_cq_data3_RW; | |
623 | }; | |
b8302363 | 624 | .EE |
4875e482 | 625 | .in |
a721e8b2 | 626 | .IP |
4875e482 MK |
627 | The |
628 | .I proxydma_info | |
629 | file contains similar information, but describes the proxy DMA queue | |
630 | (i.e., DMAs initiated by entities outside the SPU) instead. | |
631 | The file is in the following format: | |
a721e8b2 | 632 | .IP |
088a639b | 633 | .in +4n |
b8302363 | 634 | .EX |
4875e482 MK |
635 | struct spu_proxydma_info { |
636 | uint64_t proxydma_info_type; | |
637 | uint64_t proxydma_info_mask; | |
638 | uint64_t proxydma_info_status; | |
639 | struct mfc_cq_sr proxydma_info_command_data[8]; | |
640 | }; | |
b8302363 | 641 | .EE |
4875e482 | 642 | .in |
a721e8b2 | 643 | .IP |
4875e482 MK |
644 | Accessing these files requires that the SPU context is scheduled out - |
645 | frequent use can be inefficient. | |
646 | These files should not be used for normal program operation. | |
a721e8b2 | 647 | .IP |
4875e482 MK |
648 | These files are not present on contexts that have been created with the |
649 | .B SPU_CREATE_NOSCHED | |
650 | flag. | |
4875e482 | 651 | .TP |
1ae6b2c7 | 652 | .I /cntl |
4875e482 MK |
653 | This file provides access to the SPU Run Control and SPU status |
654 | registers, as an ASCII string. | |
655 | The following operations are supported: | |
656 | .RS | |
657 | .TP | |
658 | .BR read (2) | |
659 | Reads from the | |
660 | .I cntl | |
661 | file will return an ASCII string with the hex | |
662 | value of the SPU Status register. | |
663 | .TP | |
664 | .BR write (2) | |
665 | Writes to the | |
666 | .I cntl | |
667 | file will set the context's SPU Run Control register. | |
668 | .RE | |
669 | .TP | |
670 | .I /mfc | |
671 | Provides access to the Memory Flow Controller of the SPU. | |
672 | Reading from the file returns the contents of the | |
673 | SPU's MFC Tag Status register, and | |
674 | writing to the file initiates a DMA from the MFC. | |
675 | The following operations are supported: | |
676 | .RS | |
677 | .TP | |
678 | .BR write (2) | |
679 | Writes to this file need to be in the format of a MFC DMA command, | |
680 | defined as follows: | |
a721e8b2 | 681 | .IP |
088a639b | 682 | .in +4n |
b8302363 | 683 | .EX |
4875e482 MK |
684 | struct mfc_dma_command { |
685 | int32_t pad; /* reserved */ | |
686 | uint32_t lsa; /* local storage address */ | |
687 | uint64_t ea; /* effective address */ | |
688 | uint16_t size; /* transfer size */ | |
689 | uint16_t tag; /* command tag */ | |
690 | uint16_t class; /* class ID */ | |
691 | uint16_t cmd; /* command opcode */ | |
692 | }; | |
b8302363 | 693 | .EE |
4875e482 | 694 | .in |
a721e8b2 | 695 | .IP |
4875e482 MK |
696 | Writes are required to be exactly |
697 | .I sizeof(struct mfc_dma_command) | |
698 | bytes in size. | |
699 | The command will be sent to the SPU's MFC proxy queue, and the | |
700 | tag stored in the kernel (see below). | |
701 | .TP | |
702 | .BR read (2) | |
703 | Reads the contents of the tag status register. | |
704 | If the file is opened in blocking mode (i.e., without | |
705 | .BR O_NONBLOCK ), | |
706 | then the read will block until a | |
707 | DMA tag (as performed by a previous write) is complete. | |
ff40dbb3 | 708 | In nonblocking mode, |
4875e482 MK |
709 | the MFC tag status register will be returned without waiting. |
710 | .TP | |
711 | .BR poll (2) | |
712 | Calling | |
713 | .BR poll (2) | |
714 | on the | |
715 | .I mfc | |
716 | file will block until a new DMA can be | |
717 | started (by checking for | |
718 | .BR POLLOUT ) | |
719 | or until a previously started DMA | |
720 | (by checking for | |
721 | .BR POLLIN ) | |
722 | has been completed. | |
a721e8b2 | 723 | .IP |
4875e482 | 724 | .I /mss |
a6c99d33 | 725 | Provides access to the MFC MultiSource Synchronization (MSS) facility. |
4875e482 MK |
726 | By |
727 | .BR mmap (2)-ing | |
a46458f9 | 728 | this file, processes can access the MSS area of the SPU. |
a721e8b2 | 729 | .IP |
4875e482 MK |
730 | The following operations are supported: |
731 | .TP | |
732 | .BR mmap (2) | |
733 | Mapping | |
734 | .B mss | |
735 | into the process address space gives access to the SPU MSS area | |
736 | within the process address space. | |
737 | Only | |
738 | .B MAP_SHARED | |
739 | mappings are allowed. | |
740 | .RE | |
741 | .TP | |
742 | .I /psmap | |
743 | Provides access to the whole problem-state mapping of the SPU. | |
744 | Applications can use this area to interface to the SPU, rather than | |
66516789 MK |
745 | writing to individual register files in |
746 | .BR spufs . | |
a721e8b2 | 747 | .IP |
4875e482 MK |
748 | The following operations are supported: |
749 | .RS | |
750 | .TP | |
751 | .BR mmap (2) | |
752 | Mapping | |
59bd36b0 | 753 | .B psmap |
4875e482 MK |
754 | gives a process a direct map of the SPU problem state area. |
755 | Only | |
756 | .B MAP_SHARED | |
757 | mappings are supported. | |
758 | .RE | |
759 | .TP | |
b49c2acb | 760 | .I /phys\-id |
4875e482 MK |
761 | Read-only file containing the physical SPU number that the SPU context |
762 | is running on. | |
763 | When the context is not running, this file contains the | |
c3074d70 | 764 | string "\-1". |
a721e8b2 | 765 | .IP |
4875e482 | 766 | The physical SPU number is given by an ASCII hex string. |
4875e482 | 767 | .TP |
b49c2acb | 768 | .I /object\-id |
4875e482 MK |
769 | Allows applications to store (or retrieve) a single 64-bit ID into the |
770 | context. | |
771 | This ID is later used by profiling tools to uniquely identify | |
772 | the context. | |
773 | .RS | |
774 | .TP | |
775 | .BR write (2) | |
776 | By writing an ASCII hex value into this file, applications can set the | |
777 | object ID of the SPU context. | |
778 | Any previous value of the object ID is overwritten. | |
779 | .TP | |
780 | .BR read (2) | |
781 | Reading this file gives an ASCII hex string representing the object ID | |
782 | for this SPU context. | |
deb39835 | 783 | .RE |
a14af333 | 784 | .SH EXAMPLES |
9249e0f0 | 785 | To automatically |
e90cbd94 | 786 | .BR mount (8) |
9249e0f0 AC |
787 | the SPU filesystem when booting, at the location |
788 | .I /spu | |
789 | chosen by the user, put this line into the | |
e90cbd94 | 790 | .BR fstab (5) |
9249e0f0 AC |
791 | configuration file: |
792 | .EX | |
793 | none /spu spufs gid=spu 0 0 | |
794 | .EE | |
6282f7bd | 795 | .\" .SH AUTHORS |
4875e482 MK |
796 | .\" Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>, |
797 | .\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org> | |
6282f7bd MK |
798 | .SH SEE ALSO |
799 | .BR close (2), | |
800 | .BR spu_create (2), | |
4875e482 | 801 | .BR spu_run (2), |
173fe7e7 | 802 | .BR capabilities (7) |
c6d039a3 | 803 | .P |
4875e482 | 804 | .I The Cell Broadband Engine Architecture (CBEA) specification |