spe_context_create_affinity - Create a new SPE context with an affinity constraint.
#include <libspe2.h>
spe_context_ptr_t spe_context_create_affinity(unsigned int flags, spe_context_ptr_t affinity_neighbor, spe_gang_context_ptr_t gang)
| Parameters | |
| flags | A bit-wise OR of modifiers that are applied when the SPE context is created. |
| affinity_neighbor | The affinity_neighbor parameter identifies a previously created SPE context in the named gang. A NULL value may be specified for the initial SPE context. Or the spe_context_create() routine may be used to create the initial SPE context. The affinity_neighbor must be in the same gang as the newly created SPE context. |
| gang | Associate the new SPE context with this gang context. NULL is not permitted here, because affinity constraints can only be specified for members of the same gang. |
This function allows an SPE context to be created and placed next to another previously created SPE context. SPE-SPE Affinity is always specified in affinity pairs. The SPE scheduler honors this relationship by scheduling the SPE contexts on physically adjacent SPUs. This function can be used to create a chain of SPE contexts that consumes all of the available SPE resources on a Cell BE, but not more. If you want to use additional SPE resources, you must create a separate gang or individual SPE contexts for that purpose. All SPE contexts in the gang must be created before you run any SPE contexts in the gang.
On success, a pointer to the newly created SPE context is returned.
On error, NULL is returned and errno is set to indicate the error.
Possible errors include:
| ENOTSUP | Platform does not support affinity (PlayStation 3 does not support affinity). |
| EEXIST | Too many references to affinity neighbor. Too many SPE contexts with memory affinity specified. |
| ESRCH | No such SPE context (affinity_neighbor is not valid). No such gang context (gang context could not be found). |
| EINVAL | Argument is not valid (bad flag value). |
| EPERM | Lack of resources (too many isolated SPUs). The process does not have permission to add threads to the designated SPE gang context, or to use the SPU_MAP_PS setting. |
| ENOMEM | The SPE context could not be allocated due to lack of system resources. |
| EFAULT | A runtime error of the underlying operating system service occurred. |
| EBUSY | Cannot add more SPE affinity contexts because an SPE context in the gang is already running. |
| ENODEV | An isolated SPE context has been requested but the system is not isolation-enabled. |
The following values for flags are accepted:
| Flags | Description |
| SPE_EVENTS_ENABLE | Event handling shall be enabled on this SPE context |
| SPE_CFG_SIGNOTIFY1_OR | Configure the SPU Signal Notification 1 Register to be in "logical OR" mode instead of the default "Overwrite" mode. |
| SPE_CFG_SIGNOTIFY2_OR | Configure the SPU Signal Notification 2 Register1 to be in "logical OR" mode instead of the default "Overwrite" mode. |
| SPE_MAP_PS | Request permission for memory-mapped access to the SPE's problem state area(s). |
| SPE_ISOLATED | This context executes on an SPU in the isolation mode. Programs loaded into contexts flagged with SPE_ISOLATED must be be correctly formatted for isolated execution. |
| SPE_ISOLATED_EMULATE | Run this context on an SPU in an emulated isolation
mode. This mode provides emulation of an isolated SPU without truly being
isolated as is intended for use by developers who need access to debug tools
during the development of their isolated applications. Programs loaded into
contexts flagged with SPE_ISOLATED_EMULATE must be correctly formatted for
isolated emulation execution. Note: (Linux) Proper operation of a PPE assisted
function call assumes the use of the ISOLATED version of the SPE library functions.
|
| SPE_AFFINITY_MEMORY | Request that the new SPE context is placed on an SPE that is considered to be the closest to main memory. Only one SPE context in the gang may be created with memory affinity. |