OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs
paffinity.h File Reference

paffinity (processor affinity) framework component interface definitions. More...

`#include "opal_config.h"`
`#include "opal/mca/mca.h"`
`#include "opal/mca/base/base.h"`

Go to the source code of this file.

## Data Structures
struct | opal_paffinity_base_cpu_set_t
| Public processor bitmask type. More...
struct | opal_paffinity_base_component_2_0_1_t
| Structure for paffinity components. More...
struct | opal_paffinity_base_module_1_1_0_t
| Structure for paffinity modules. More...

## Macros
#define | OPAL_PROC_LOCALITY_UNKNOWN 0x0000
| Process locality definitions.
#define | OPAL_PROC_NON_LOCAL 0x8000
#define | OPAL_PROC_ON_CLUSTER 0x0400
#define | OPAL_PROC_ON_CU 0x0200
#define | OPAL_PROC_ON_NODE 0x0100
#define | OPAL_PROC_ON_BOARD 0x0080
#define | OPAL_PROC_ON_NUMA 0x0040
#define | OPAL_PROC_ON_SOCKET 0x0020
#define | OPAL_PROC_ON_L3CACHE 0x0010
#define | OPAL_PROC_ON_L2CACHE 0x0008
#define | OPAL_PROC_ON_L1CACHE 0x0004
#define | OPAL_PROC_ON_CORE 0x0002
#define | OPAL_PROC_ON_HWTHREAD 0x0001
#define | OPAL_PROC_ALL_LOCAL 0x0fff
#define | OPAL_PROC_ON_LOCAL_HWTHREAD(n) ((n) & OPAL_PROC_ON_HWTHREAD)
| Process locality macros.
#define | OPAL_PROC_ON_LOCAL_CORE(n) ((n) & OPAL_PROC_ON_CORE)
#define | OPAL_PROC_ON_LOCAL_L1CACHE(n) ((n) & OPAL_PROC_ON_L1CACHE)
#define | OPAL_PROC_ON_LOCAL_L2CACHE(n) ((n) & OPAL_PROC_ON_L2CACHE)
#define | OPAL_PROC_ON_LOCAL_L3CACHE(n) ((n) & OPAL_PROC_ON_L3CACHE)
#define | OPAL_PROC_ON_LOCAL_SOCKET(n) ((n) & OPAL_PROC_ON_SOCKET)
#define | OPAL_PROC_ON_LOCAL_NUMA(n) ((n) & OPAL_PROC_ON_NUMA)
#define | OPAL_PROC_ON_LOCAL_BOARD(n) ((n) & OPAL_PROC_ON_BOARD)
#define | OPAL_PROC_ON_LOCAL_NODE(n) ((n) & OPAL_PROC_ON_NODE)
#define | OPAL_PROC_ON_LOCAL_CU(n) ((n) & OPAL_PROC_ON_CU)
#define | OPAL_PROC_ON_LOCAL_CLUSTER(n) ((n) & OPAL_PROC_ON_CLUSTER)
#define | OPAL_PAFFINITY_DO_NOT_BIND 0x01
#define | OPAL_PAFFINITY_BIND_TO_CORE 0x02
#define | OPAL_PAFFINITY_BIND_TO_SOCKET 0x04
#define | OPAL_PAFFINITY_BIND_TO_BOARD 0x08
#define | OPAL_PAFFINITY_BIND_IF_SUPPORTED 0x80
#define | OPAL_PAFFINITY_BITMASK_T_NUM_BITS (sizeof(opal_paffinity_base_bitmask_t) * 8)
#define | OPAL_PAFFINITY_BITMASK_CPU_MAX 1024
#define | OPAL_PAFFINITY_BITMASK_NUM_ELEMENTS (OPAL_PAFFINITY_BITMASK_CPU_MAX / OPAL_PAFFINITY_BITMASK_T_NUM_BITS)
#define | OPAL_PAFFINITY_CPU_SET_NUM_BYTES (OPAL_PAFFINITY_BITMASK_NUM_ELEMENTS * sizeof(opal_paffinity_base_bitmask_t))
#define | OPAL_PAFFINITY_CPU_BYTE(num) ((num) / OPAL_PAFFINITY_BITMASK_T_NUM_BITS)
#define | OPAL_PAFFINITY_CPU_BIT(num) ((num) % OPAL_PAFFINITY_BITMASK_T_NUM_BITS)
#define | OPAL_PAFFINITY_CPU_ZERO(cpuset) memset(&(cpuset), 0, sizeof(opal_paffinity_base_cpu_set_t))
| Public macro to zero out a OPAL_PAFFINITY cpu set.
#define | OPAL_PAFFINITY_CPU_SET(num, cpuset) (cpuset).bitmask[OPAL_PAFFINITY_CPU_BYTE(num)] |= ((opal_paffinity_base_bitmask_t) 1 << OPAL_PAFFINITY_CPU_BIT(num))
| Public macro to set a bit in a OPAL_PAFFINITY cpu set.
#define | OPAL_PAFFINITY_CPU_CLR(num, cpuset) (cpuset).bitmask[OPAL_PAFFINITY_CPU_BYTE(num)] &= ~((opal_paffinity_base_bitmask_t) 1 << OPAL_PAFFINITY_CPU_BIT(num))
| Public macro to clear a bit in a OPAL_PAFFINITY cpu set.
#define | OPAL_PAFFINITY_CPU_ISSET(num, cpuset) (0 != (((cpuset).bitmask[OPAL_PAFFINITY_CPU_BYTE(num)]) & ((opal_paffinity_base_bitmask_t) 1 << OPAL_PAFFINITY_CPU_BIT(num))))
| Public macro to test if a bit is set in a OPAL_PAFFINITY cpu set.
#define | OPAL_PAFFINITY_PROCESS_IS_BOUND(cpuset, bound)
| Public macro to test if a process is bound anywhere. More...
#define | OPAL_PAFFINITY_BASE_VERSION_2_0_1

## Typedefs
typedef uint16_t | opal_paffinity_locality_t
typedef unsigned long int | opal_paffinity_base_bitmask_t
| Buffer type for paffinity processor masks. More...
typedef struct opal_paffinity_base_cpu_set_t | opal_paffinity_base_cpu_set_t
| Public processor bitmask type.
typedef int(* | opal_paffinity_base_module_init_1_1_0_fn_t )(void)
| Module initialization function. More...
typedef int(* | opal_paffinity_base_module_set_fn_t )(opal_paffinity_base_cpu_set_t cpumask)
| Module function to set this process' affinity to a specific set of PHYSICAL CPUs.
typedef int(* | opal_paffinity_base_module_get_fn_t )(opal_paffinity_base_cpu_set_t *cpumask)
| Module function to get this process' affinity to a specific set of PHYSICAL CPUs. More...
typedef int(* | opal_paffinity_base_module_get_map_to_processor_id_fn_t )(int physical_socket, int physical_core, int *physical_processor_id)
| Returns mapping of PHYSICAL socket:core -> PHYSICAL processor id. More...
typedef int(* | opal_paffinity_base_module_get_map_to_socket_core_fn_t )(int physical_processor_id, int *physical_socket, int *physical_core)
| Provides mapping of PHYSICAL processor id -> PHYSICAL socket:core. More...
typedef int(* | opal_paffinity_base_module_get_processor_info_fn_t )(int *num_processors)
| Provides number of LOGICAL processors in a host. More...
typedef int(* | opal_paffinity_base_module_get_socket_info_fn_t )(int *num_sockets)
| Provides the number of LOGICAL sockets in a host. More...
typedef int(* | opal_paffinity_base_module_get_core_info_fn_t )(int physical_socket, int *num_cores)
| Provides the number of LOGICAL cores in a PHYSICAL socket. More...
typedef int(* | opal_paffinity_base_module_get_physical_processor_id_fn_t )(int logical_processor_id, int *physical_processor_id)
| Provide the PHYSICAL processor ID that corresponds to the given LOGICAL processor ID. More...
typedef int(* | opal_paffinity_base_module_get_physical_socket_id_fn_t )(int logical_socket_id, int *physical_socket_id)
| Provide the PHYSICAL socket ID that corresponds to the given LOGICAL socket ID. More...
typedef int(* | opal_paffinity_base_module_get_physical_core_id_fn_t )(int physical_socket_id, int logical_core_id, int *physical_core_id)
| Provide the PHYSICAL core ID that corresponds to the given LOGICAL core ID on the given PHYSICAL socket ID. More...
typedef int(* | opal_paffinity_base_module_finalize_fn_t )(void)
| Module finalize function. More...
typedef struct opal_paffinity_base_component_2_0_1_t | opal_paffinity_base_component_2_0_1_t
| Convenience typedef.
typedef struct opal_paffinity_base_component_2_0_1_t | opal_paffinity_base_component_t
typedef struct opal_paffinity_base_module_1_1_0_t | opal_paffinity_base_module_1_1_0_t
| Convenience typedef.
typedef struct opal_paffinity_base_module_1_1_0_t | opal_paffinity_base_module_t

## Detailed Description

paffinity (processor affinity) framework component interface definitions.

Intent

This framework is used to support the OS-specific API for placement of processes on processors. It does not decide scheduling issues – it is simply for assigning the current process it to a specific processor set. As such, the components are likely to be extremely short/simple – there will likely be one component for each OS/API that we support (e.g., Linux, IRIX, etc.). As a direct consequence, there will likely only be one component that is useable on a given platform (making selection easy).

It is not an error if there is no paffinity component available; processor affinity services are simply not available. Hence, paffinity component functions are invoked through short wrapper functions in paffinity/base (that check to see if there is a selected component before invoking function pointers). If there is no selected component, they return an appropriate error code.

In the paffinity interface, we make the distinction between LOGICAL and PHYSICAL processors. LOGICAL processors are defined to have some corresponding PHYSICAL processor that both exists and is currently online. LOGICAL processors numbered countiguously starting with 0. PHYSICAL processors are numbered according to the underlying operating system; they are represented by integers, but no guarantees are made about their values.

Hence, LOGICAL processor IDs are convenient for humans and are in the range of [0,N-1] (assuming N processors are currently online). Each LOGICAL processor has a 1:1 relationship with a PHYSICAL processor, but the PHYSICAL processor's ID can be any unique integer value.

***NOTE*** Obtaining information about socket/core IDs is not well supported in many OS's. Programmers using this paffinity interface should fully expect to sometimes get OPAL_ERR_NOT_SUPPORTED back when calling such functions.

General scheme

The component has one function: query(). It simply returns a priority (for the unlikely event where there are multiple components available on a given platform).

Note that the only real paffinity module that matters these days is hwloc. Its module functions will return OPAL_ERR_NOT_INITIALIZED if the underlying hwloc system has not yet been initialized (which may not have occured yet since we tend to only initialize hwloc if/when necessary – it's not nice to have N processes on a server all initialize hwloc simultaneously, because they might all simultaneously bang on /proc and /syst, etc.).

The module has the following functions:

- module_init: initialze the module
- set: set this process's affinity to a specific processor set
- get: get this process's processor affinity set
- map physical (socket ID, core ID) -> physical processor ID
- map physical processor ID -> physical (socket ID, core ID)
- get the number of logical processors
- get the number of logical sockets
- get the number of logical cores on a specific socket
- map logical processor ID -> physical processor ID
- map logical socket ID -> physical socket ID
- map physical socket ID, logical core ID -> physical core ID
- module_finalize: finalize the module

## Macro Definition Documentation

#define OPAL_PAFFINITY_BASE_VERSION_2_0_1

Value:
MCA_BASE_VERSION_2_0_0, \
"paffinity", 2, 0, 1

#define OPAL_PAFFINITY_PROCESS_IS_BOUND | ( |  | cpuset,
|  |  | bound
| ) |  |

Value:
do { \
int i, num_processors, num_bound; \
*(bound) = false; \
if (OPAL_SUCCESS == \
opal_paffinity_base_get_processor_info(&num_processors)) { \
num_bound = 0; \
for (i = 0; i < OPAL_PAFFINITY_BITMASK_CPU_MAX; i++) { \
if (OPAL_PAFFINITY_CPU_ISSET(i, (cpuset))) { \
num_bound++; \
} \
} \
if (0 < num_bound && (1 == num_processors || \
num_bound < num_processors)) { \
*(bound) = true; \
} \
} \
} while(0);
OPAL_PAFFINITY_CPU_ISSET
#define OPAL_PAFFINITY_CPU_ISSET(num, cpuset)
Public macro to test if a bit is set in a OPAL_PAFFINITY cpu set.
Definition: paffinity.h:224

Public macro to test if a process is bound anywhere.

## Typedef Documentation

typedef unsigned long int opal_paffinity_base_bitmask_t

Buffer type for paffinity processor masks.

Copied almost directly from PLPA.

typedef int(* opal_paffinity_base_module_finalize_fn_t)(void)

Module finalize function.

Invoked by the base on the selected module when the paffinity framework is being shut down.

typedef int(* opal_paffinity_base_module_get_core_info_fn_t)(int physical_socket, int *num_cores)

Provides the number of LOGICAL cores in a PHYSICAL socket.

Returns OPAL_SUCCESS or OPAL_ERR_NOT_SUPPORTED if not supported.

typedef int(* opal_paffinity_base_module_get_fn_t)(opal_paffinity_base_cpu_set_t *cpumask)

Module function to get this process' affinity to a specific set of PHYSICAL CPUs.

Returns any binding in the cpumask. This function -only- returns something other than OPAL_SUCCESS if an actual error is encountered. You will need to check the mask to find out if this process is actually bound somewhere specific - a macro for that purpose is provided above

typedef int(* opal_paffinity_base_module_get_map_to_processor_id_fn_t)(int physical_socket, int physical_core, int *physical_processor_id)

Returns mapping of PHYSICAL socket:core -> PHYSICAL processor id.

Return OPAL_SUCCESS or OPAL_ERR_NOT_SUPPORTED if not supported

typedef int(* opal_paffinity_base_module_get_map_to_socket_core_fn_t)(int physical_processor_id, int *physical_socket, int *physical_core)

Provides mapping of PHYSICAL processor id -> PHYSICAL socket:core.

Return OPAL_SUCCESS or OPAL_ERR_NOT_SUPPORTED if not supported

typedef int(* opal_paffinity_base_module_get_physical_core_id_fn_t)(int physical_socket_id, int logical_core_id, int *physical_core_id)

Provide the PHYSICAL core ID that corresponds to the given LOGICAL core ID on the given PHYSICAL socket ID.

Return OPAL_ERR_NOT_SUPPORTED if not supported.

typedef int(* opal_paffinity_base_module_get_physical_processor_id_fn_t)(int logical_processor_id, int *physical_processor_id)

Provide the PHYSICAL processor ID that corresponds to the given LOGICAL processor ID.

Return OPAL_ERR_NOT_SUPPORTED if not supported.

typedef int(* opal_paffinity_base_module_get_physical_socket_id_fn_t)(int logical_socket_id, int *physical_socket_id)

Provide the PHYSICAL socket ID that corresponds to the given LOGICAL socket ID.

Return OPAL_ERR_NOT_SUPPORTED if not supported.

typedef int(* opal_paffinity_base_module_get_processor_info_fn_t)(int *num_processors)

Provides number of LOGICAL processors in a host.

Return OPAL_SUCCESS or OPAL_ERR_NOT_SUPPORTED if not supported

typedef int(* opal_paffinity_base_module_get_socket_info_fn_t)(int *num_sockets)

Provides the number of LOGICAL sockets in a host.

Return OPAL_SUCCESS or OPAL_ERR_NOT_SUPPORTED if not supported

typedef int(* opal_paffinity_base_module_init_1_1_0_fn_t)(void)

Module initialization function.

Should return OPAL_SUCCESS.