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