1299cd274SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2299cd274SMauro Carvalho Chehab 3299cd274SMauro Carvalho Chehab===== 4299cd274SMauro Carvalho Chehabspufs 5299cd274SMauro Carvalho Chehab===== 6299cd274SMauro Carvalho Chehab 7299cd274SMauro Carvalho ChehabName 8299cd274SMauro Carvalho Chehab==== 9299cd274SMauro Carvalho Chehab 10299cd274SMauro Carvalho Chehab spufs - the SPU file system 11299cd274SMauro Carvalho Chehab 12299cd274SMauro Carvalho Chehab 13299cd274SMauro Carvalho ChehabDescription 14299cd274SMauro Carvalho Chehab=========== 15299cd274SMauro Carvalho Chehab 16299cd274SMauro Carvalho Chehab The SPU file system is used on PowerPC machines that implement the Cell 17299cd274SMauro Carvalho Chehab Broadband Engine Architecture in order to access Synergistic Processor 18299cd274SMauro Carvalho Chehab Units (SPUs). 19299cd274SMauro Carvalho Chehab 20299cd274SMauro Carvalho Chehab The file system provides a name space similar to posix shared memory or 21299cd274SMauro Carvalho Chehab message queues. Users that have write permissions on the file system 22299cd274SMauro Carvalho Chehab can use spu_create(2) to establish SPU contexts in the spufs root. 23299cd274SMauro Carvalho Chehab 24299cd274SMauro Carvalho Chehab Every SPU context is represented by a directory containing a predefined 25299cd274SMauro Carvalho Chehab set of files. These files can be used for manipulating the state of the 26299cd274SMauro Carvalho Chehab logical SPU. Users can change permissions on those files, but not actu- 27299cd274SMauro Carvalho Chehab ally add or remove files. 28299cd274SMauro Carvalho Chehab 29299cd274SMauro Carvalho Chehab 30299cd274SMauro Carvalho ChehabMount Options 31299cd274SMauro Carvalho Chehab============= 32299cd274SMauro Carvalho Chehab 33299cd274SMauro Carvalho Chehab uid=<uid> 34299cd274SMauro Carvalho Chehab set the user owning the mount point, the default is 0 (root). 35299cd274SMauro Carvalho Chehab 36299cd274SMauro Carvalho Chehab gid=<gid> 37299cd274SMauro Carvalho Chehab set the group owning the mount point, the default is 0 (root). 38299cd274SMauro Carvalho Chehab 39299cd274SMauro Carvalho Chehab 40299cd274SMauro Carvalho ChehabFiles 41299cd274SMauro Carvalho Chehab===== 42299cd274SMauro Carvalho Chehab 43299cd274SMauro Carvalho Chehab The files in spufs mostly follow the standard behavior for regular sys- 44299cd274SMauro Carvalho Chehab tem calls like read(2) or write(2), but often support only a subset of 45299cd274SMauro Carvalho Chehab the operations supported on regular file systems. This list details the 46299cd274SMauro Carvalho Chehab supported operations and the deviations from the behaviour in the 47299cd274SMauro Carvalho Chehab respective man pages. 48299cd274SMauro Carvalho Chehab 49299cd274SMauro Carvalho Chehab All files that support the read(2) operation also support readv(2) and 50299cd274SMauro Carvalho Chehab all files that support the write(2) operation also support writev(2). 51299cd274SMauro Carvalho Chehab All files support the access(2) and stat(2) family of operations, but 52299cd274SMauro Carvalho Chehab only the st_mode, st_nlink, st_uid and st_gid fields of struct stat 53299cd274SMauro Carvalho Chehab contain reliable information. 54299cd274SMauro Carvalho Chehab 55299cd274SMauro Carvalho Chehab All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera- 56299cd274SMauro Carvalho Chehab tions, but will not be able to grant permissions that contradict the 57299cd274SMauro Carvalho Chehab possible operations, e.g. read access on the wbox file. 58299cd274SMauro Carvalho Chehab 59299cd274SMauro Carvalho Chehab The current set of files is: 60299cd274SMauro Carvalho Chehab 61299cd274SMauro Carvalho Chehab 62299cd274SMauro Carvalho Chehab /mem 63299cd274SMauro Carvalho Chehab the contents of the local storage memory of the SPU. This can be 64299cd274SMauro Carvalho Chehab accessed like a regular shared memory file and contains both code and 65299cd274SMauro Carvalho Chehab data in the address space of the SPU. The possible operations on an 66299cd274SMauro Carvalho Chehab open mem file are: 67299cd274SMauro Carvalho Chehab 68299cd274SMauro Carvalho Chehab read(2), pread(2), write(2), pwrite(2), lseek(2) 69299cd274SMauro Carvalho Chehab These operate as documented, with the exception that seek(2), 70299cd274SMauro Carvalho Chehab write(2) and pwrite(2) are not supported beyond the end of the 71299cd274SMauro Carvalho Chehab file. The file size is the size of the local storage of the SPU, 72299cd274SMauro Carvalho Chehab which normally is 256 kilobytes. 73299cd274SMauro Carvalho Chehab 74299cd274SMauro Carvalho Chehab mmap(2) 75299cd274SMauro Carvalho Chehab Mapping mem into the process address space gives access to the 76299cd274SMauro Carvalho Chehab SPU local storage within the process address space. Only 77299cd274SMauro Carvalho Chehab MAP_SHARED mappings are allowed. 78299cd274SMauro Carvalho Chehab 79299cd274SMauro Carvalho Chehab 80299cd274SMauro Carvalho Chehab /mbox 81299cd274SMauro Carvalho Chehab The first SPU to CPU communication mailbox. This file is read-only and 82299cd274SMauro Carvalho Chehab can be read in units of 32 bits. The file can only be used in non- 83299cd274SMauro Carvalho Chehab blocking mode and it even poll() will not block on it. The possible 84299cd274SMauro Carvalho Chehab operations on an open mbox file are: 85299cd274SMauro Carvalho Chehab 86299cd274SMauro Carvalho Chehab read(2) 87299cd274SMauro Carvalho Chehab If a count smaller than four is requested, read returns -1 and 88299cd274SMauro Carvalho Chehab sets errno to EINVAL. If there is no data available in the mail 89299cd274SMauro Carvalho Chehab box, the return value is set to -1 and errno becomes EAGAIN. 90299cd274SMauro Carvalho Chehab When data has been read successfully, four bytes are placed in 91299cd274SMauro Carvalho Chehab the data buffer and the value four is returned. 92299cd274SMauro Carvalho Chehab 93299cd274SMauro Carvalho Chehab 94299cd274SMauro Carvalho Chehab /ibox 95299cd274SMauro Carvalho Chehab The second SPU to CPU communication mailbox. This file is similar to 96299cd274SMauro Carvalho Chehab the first mailbox file, but can be read in blocking I/O mode, and the 97299cd274SMauro Carvalho Chehab poll family of system calls can be used to wait for it. The possible 98299cd274SMauro Carvalho Chehab operations on an open ibox file are: 99299cd274SMauro Carvalho Chehab 100299cd274SMauro Carvalho Chehab read(2) 101299cd274SMauro Carvalho Chehab If a count smaller than four is requested, read returns -1 and 102299cd274SMauro Carvalho Chehab sets errno to EINVAL. If there is no data available in the mail 103299cd274SMauro Carvalho Chehab box and the file descriptor has been opened with O_NONBLOCK, the 104299cd274SMauro Carvalho Chehab return value is set to -1 and errno becomes EAGAIN. 105299cd274SMauro Carvalho Chehab 106299cd274SMauro Carvalho Chehab If there is no data available in the mail box and the file 107299cd274SMauro Carvalho Chehab descriptor has been opened without O_NONBLOCK, the call will 108299cd274SMauro Carvalho Chehab block until the SPU writes to its interrupt mailbox channel. 109299cd274SMauro Carvalho Chehab When data has been read successfully, four bytes are placed in 110299cd274SMauro Carvalho Chehab the data buffer and the value four is returned. 111299cd274SMauro Carvalho Chehab 112299cd274SMauro Carvalho Chehab poll(2) 113299cd274SMauro Carvalho Chehab Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever 114299cd274SMauro Carvalho Chehab data is available for reading. 115299cd274SMauro Carvalho Chehab 116299cd274SMauro Carvalho Chehab 117299cd274SMauro Carvalho Chehab /wbox 118299cd274SMauro Carvalho Chehab The CPU to SPU communation mailbox. It is write-only and can be written 119299cd274SMauro Carvalho Chehab in units of 32 bits. If the mailbox is full, write() will block and 120299cd274SMauro Carvalho Chehab poll can be used to wait for it becoming empty again. The possible 121299cd274SMauro Carvalho Chehab operations on an open wbox file are: write(2) If a count smaller than 122299cd274SMauro Carvalho Chehab four is requested, write returns -1 and sets errno to EINVAL. If there 123299cd274SMauro Carvalho Chehab is no space available in the mail box and the file descriptor has been 124299cd274SMauro Carvalho Chehab opened with O_NONBLOCK, the return value is set to -1 and errno becomes 125299cd274SMauro Carvalho Chehab EAGAIN. 126299cd274SMauro Carvalho Chehab 127299cd274SMauro Carvalho Chehab If there is no space available in the mail box and the file descriptor 128299cd274SMauro Carvalho Chehab has been opened without O_NONBLOCK, the call will block until the SPU 129299cd274SMauro Carvalho Chehab reads from its PPE mailbox channel. When data has been read success- 130299cd274SMauro Carvalho Chehab fully, four bytes are placed in the data buffer and the value four is 131299cd274SMauro Carvalho Chehab returned. 132299cd274SMauro Carvalho Chehab 133299cd274SMauro Carvalho Chehab poll(2) 134299cd274SMauro Carvalho Chehab Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever 135299cd274SMauro Carvalho Chehab space is available for writing. 136299cd274SMauro Carvalho Chehab 137299cd274SMauro Carvalho Chehab 138299cd274SMauro Carvalho Chehab /mbox_stat, /ibox_stat, /wbox_stat 139299cd274SMauro Carvalho Chehab Read-only files that contain the length of the current queue, i.e. how 140299cd274SMauro Carvalho Chehab many words can be read from mbox or ibox or how many words can be 141299cd274SMauro Carvalho Chehab written to wbox without blocking. The files can be read only in 4-byte 142299cd274SMauro Carvalho Chehab units and return a big-endian binary integer number. The possible 143299cd274SMauro Carvalho Chehab operations on an open ``*box_stat`` file are: 144299cd274SMauro Carvalho Chehab 145299cd274SMauro Carvalho Chehab read(2) 146299cd274SMauro Carvalho Chehab If a count smaller than four is requested, read returns -1 and 147299cd274SMauro Carvalho Chehab sets errno to EINVAL. Otherwise, a four byte value is placed in 148299cd274SMauro Carvalho Chehab the data buffer, containing the number of elements that can be 149299cd274SMauro Carvalho Chehab read from (for mbox_stat and ibox_stat) or written to (for 150299cd274SMauro Carvalho Chehab wbox_stat) the respective mail box without blocking or resulting 151299cd274SMauro Carvalho Chehab in EAGAIN. 152299cd274SMauro Carvalho Chehab 153299cd274SMauro Carvalho Chehab 154299cd274SMauro Carvalho Chehab /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /srr0 155299cd274SMauro Carvalho Chehab Internal registers of the SPU. The representation is an ASCII string 156299cd274SMauro Carvalho Chehab with the numeric value of the next instruction to be executed. These 157299cd274SMauro Carvalho Chehab can be used in read/write mode for debugging, but normal operation of 158299cd274SMauro Carvalho Chehab programs should not rely on them because access to any of them except 159299cd274SMauro Carvalho Chehab npc requires an SPU context save and is therefore very inefficient. 160299cd274SMauro Carvalho Chehab 161299cd274SMauro Carvalho Chehab The contents of these files are: 162299cd274SMauro Carvalho Chehab 163299cd274SMauro Carvalho Chehab =================== =================================== 164299cd274SMauro Carvalho Chehab npc Next Program Counter 165299cd274SMauro Carvalho Chehab decr SPU Decrementer 166299cd274SMauro Carvalho Chehab decr_status Decrementer Status 167299cd274SMauro Carvalho Chehab spu_tag_mask MFC tag mask for SPU DMA 168299cd274SMauro Carvalho Chehab event_mask Event mask for SPU interrupts 169299cd274SMauro Carvalho Chehab srr0 Interrupt Return address register 170299cd274SMauro Carvalho Chehab =================== =================================== 171299cd274SMauro Carvalho Chehab 172299cd274SMauro Carvalho Chehab 173299cd274SMauro Carvalho Chehab The possible operations on an open npc, decr, decr_status, 174299cd274SMauro Carvalho Chehab spu_tag_mask, event_mask or srr0 file are: 175299cd274SMauro Carvalho Chehab 176299cd274SMauro Carvalho Chehab read(2) 177299cd274SMauro Carvalho Chehab When the count supplied to the read call is shorter than the 178299cd274SMauro Carvalho Chehab required length for the pointer value plus a newline character, 179299cd274SMauro Carvalho Chehab subsequent reads from the same file descriptor will result in 180299cd274SMauro Carvalho Chehab completing the string, regardless of changes to the register by 181299cd274SMauro Carvalho Chehab a running SPU task. When a complete string has been read, all 182299cd274SMauro Carvalho Chehab subsequent read operations will return zero bytes and a new file 183299cd274SMauro Carvalho Chehab descriptor needs to be opened to read the value again. 184299cd274SMauro Carvalho Chehab 185299cd274SMauro Carvalho Chehab write(2) 186299cd274SMauro Carvalho Chehab A write operation on the file results in setting the register to 187299cd274SMauro Carvalho Chehab the value given in the string. The string is parsed from the 188299cd274SMauro Carvalho Chehab beginning to the first non-numeric character or the end of the 189299cd274SMauro Carvalho Chehab buffer. Subsequent writes to the same file descriptor overwrite 190299cd274SMauro Carvalho Chehab the previous setting. 191299cd274SMauro Carvalho Chehab 192299cd274SMauro Carvalho Chehab 193299cd274SMauro Carvalho Chehab /fpcr 194299cd274SMauro Carvalho Chehab This file gives access to the Floating Point Status and Control Regis- 195299cd274SMauro Carvalho Chehab ter as a four byte long file. The operations on the fpcr file are: 196299cd274SMauro Carvalho Chehab 197299cd274SMauro Carvalho Chehab read(2) 198299cd274SMauro Carvalho Chehab If a count smaller than four is requested, read returns -1 and 199299cd274SMauro Carvalho Chehab sets errno to EINVAL. Otherwise, a four byte value is placed in 200299cd274SMauro Carvalho Chehab the data buffer, containing the current value of the fpcr regis- 201299cd274SMauro Carvalho Chehab ter. 202299cd274SMauro Carvalho Chehab 203299cd274SMauro Carvalho Chehab write(2) 204299cd274SMauro Carvalho Chehab If a count smaller than four is requested, write returns -1 and 205299cd274SMauro Carvalho Chehab sets errno to EINVAL. Otherwise, a four byte value is copied 206299cd274SMauro Carvalho Chehab from the data buffer, updating the value of the fpcr register. 207299cd274SMauro Carvalho Chehab 208299cd274SMauro Carvalho Chehab 209299cd274SMauro Carvalho Chehab /signal1, /signal2 210299cd274SMauro Carvalho Chehab The two signal notification channels of an SPU. These are read-write 211299cd274SMauro Carvalho Chehab files that operate on a 32 bit word. Writing to one of these files 212299cd274SMauro Carvalho Chehab triggers an interrupt on the SPU. The value written to the signal 213299cd274SMauro Carvalho Chehab files can be read from the SPU through a channel read or from host user 214299cd274SMauro Carvalho Chehab space through the file. After the value has been read by the SPU, it 215299cd274SMauro Carvalho Chehab is reset to zero. The possible operations on an open signal1 or sig- 216299cd274SMauro Carvalho Chehab nal2 file are: 217299cd274SMauro Carvalho Chehab 218299cd274SMauro Carvalho Chehab read(2) 219299cd274SMauro Carvalho Chehab If a count smaller than four is requested, read returns -1 and 220299cd274SMauro Carvalho Chehab sets errno to EINVAL. Otherwise, a four byte value is placed in 221299cd274SMauro Carvalho Chehab the data buffer, containing the current value of the specified 222299cd274SMauro Carvalho Chehab signal notification register. 223299cd274SMauro Carvalho Chehab 224299cd274SMauro Carvalho Chehab write(2) 225299cd274SMauro Carvalho Chehab If a count smaller than four is requested, write returns -1 and 226299cd274SMauro Carvalho Chehab sets errno to EINVAL. Otherwise, a four byte value is copied 227299cd274SMauro Carvalho Chehab from the data buffer, updating the value of the specified signal 228299cd274SMauro Carvalho Chehab notification register. The signal notification register will 229299cd274SMauro Carvalho Chehab either be replaced with the input data or will be updated to the 230*e2815b71SRandy Dunlap bitwise OR of the old value and the input data, depending on the 231299cd274SMauro Carvalho Chehab contents of the signal1_type, or signal2_type respectively, 232299cd274SMauro Carvalho Chehab file. 233299cd274SMauro Carvalho Chehab 234299cd274SMauro Carvalho Chehab 235299cd274SMauro Carvalho Chehab /signal1_type, /signal2_type 236299cd274SMauro Carvalho Chehab These two files change the behavior of the signal1 and signal2 notifi- 237299cd274SMauro Carvalho Chehab cation files. The contain a numerical ASCII string which is read as 238299cd274SMauro Carvalho Chehab either "1" or "0". In mode 0 (overwrite), the hardware replaces the 239299cd274SMauro Carvalho Chehab contents of the signal channel with the data that is written to it. in 240299cd274SMauro Carvalho Chehab mode 1 (logical OR), the hardware accumulates the bits that are subse- 241299cd274SMauro Carvalho Chehab quently written to it. The possible operations on an open signal1_type 242299cd274SMauro Carvalho Chehab or signal2_type file are: 243299cd274SMauro Carvalho Chehab 244299cd274SMauro Carvalho Chehab read(2) 245299cd274SMauro Carvalho Chehab When the count supplied to the read call is shorter than the 246299cd274SMauro Carvalho Chehab required length for the digit plus a newline character, subse- 247299cd274SMauro Carvalho Chehab quent reads from the same file descriptor will result in com- 248299cd274SMauro Carvalho Chehab pleting the string. When a complete string has been read, all 249299cd274SMauro Carvalho Chehab subsequent read operations will return zero bytes and a new file 250299cd274SMauro Carvalho Chehab descriptor needs to be opened to read the value again. 251299cd274SMauro Carvalho Chehab 252299cd274SMauro Carvalho Chehab write(2) 253299cd274SMauro Carvalho Chehab A write operation on the file results in setting the register to 254299cd274SMauro Carvalho Chehab the value given in the string. The string is parsed from the 255299cd274SMauro Carvalho Chehab beginning to the first non-numeric character or the end of the 256299cd274SMauro Carvalho Chehab buffer. Subsequent writes to the same file descriptor overwrite 257299cd274SMauro Carvalho Chehab the previous setting. 258299cd274SMauro Carvalho Chehab 259299cd274SMauro Carvalho Chehab 260299cd274SMauro Carvalho ChehabExamples 261299cd274SMauro Carvalho Chehab======== 262299cd274SMauro Carvalho Chehab /etc/fstab entry 263299cd274SMauro Carvalho Chehab none /spu spufs gid=spu 0 0 264299cd274SMauro Carvalho Chehab 265299cd274SMauro Carvalho Chehab 266299cd274SMauro Carvalho ChehabAuthors 267299cd274SMauro Carvalho Chehab======= 268299cd274SMauro Carvalho Chehab Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>, 269299cd274SMauro Carvalho Chehab Ulrich Weigand <Ulrich.Weigand@de.ibm.com> 270299cd274SMauro Carvalho Chehab 271299cd274SMauro Carvalho ChehabSee Also 272299cd274SMauro Carvalho Chehab======== 273299cd274SMauro Carvalho Chehab capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7) 274