spe_image_open - Open an SPE ELF executable and map it into system memory.
#include <libspe2.h>
spe_program_handle_t *spe_image_open (const char *filename)
| Parameters | |
| filename | Specifies the filename of an SPE ELF executable to be loaded and mapped into system memory. |
spe_open_image opens an SPE ELF executable indicated by filename and maps it into system memory. The result is a pointer to an SPE program handle which can then be used with spe_program_load to load this SPE main program into the local store of an SPE before running it with spe_context_run. The file containing the SPE executable must have execution access rights. SPE ELF objects loaded using this function are not shared with other applications and processes.
It can be more convenient to embed SPE ELF objects directly within the PPE executable using the linker and an "embed_spu" (or equivalent) tool (see toolchain documentation). In this case, SPE ELF objects are converted to PPE static or shared libraries with symbols, which point to the SPE ELF objects after these special libraries are loaded.
These libraries are then linked with the associated PPE code to provide a direct symbol reference to the SPE ELF object. The symbols in this scheme are equivalent to the address returned from the spe_image_open function and can be used as SPE program handles by spe_program_load. SPE ELF objects created using the embedding approach can be shared between processes.
On success, a non-null handle to the mapped SPE ELF object is returned.
On error, NULL is returned and errno is set to indicate the error.
Possible errors include:
| EACCES | The calling process does not have the necessary permissions to access the specified file. |
| EFAULT | The filename parameter points to an address that was not contained in the calling process's address space. |
| other | A number of other errno values could be returned by the open(2), fstat(2), or mmap(2) system calls which may be utilized by the spe_image_open function. |