PLPA Overview:
General information about the PLPA

The API provides 3 main functions and 4 macros:

• plpa_api_probe(void): Returns an enum indicating the level of processor affinity support on your system that PLPA was able to discover. It will be one of the following:
  • PLPA_PROBE_OK: Indicates that the PLPA was able to successfully discover the version of processor affinity API used on the system; future calls to other PLPA functions should be successful.
  • PLPA_PROBE_NOT_SUPPORTED: Indicates that the PLPA was able to discover that processor affinity is not supported on this system. Future calls to other PLPA functions will fail.
  • PLPA_PROBE_UNKNOWN: Indicates that the PLPA was unable to discover the version of processor affinity API used on the system. Future calls to other PLPA functions will fail.
• plpa_sched_setaffinity(pid_t pid, size_t cpusetsize, const plpa_cpu_set_t *cpuset): Generally follows the behavior of the sched_setaffinity(3) library call to set the processor affinity for PID pid. The plpa_cpu_set_t type may be manipulated with the PLPA_CPU_* macros (described below). Additional error checking is performed in the PLPA; the following values may be returned:
  • 0: Success.
  • EINVAL: One of the following occurred:
    • The CPU set size provided was both larger than permissable and bits were set that would be ignored by the kernel.
    • The CPU set size provided was too small.
    • The CPU set pointer was NULL.
    • PLPA was unable to determine the processor affinity API used on this system; call plpa_api_probe() for more information.

  • ENOSYS: Processor affinity is not supported on this system.

• plpa_sched_getaffinity(pid_t pid, size_t cpusetsize, plpa_cpu_set_t *cpuset): Generally follows the behavior of the sched_getaffinity(3) library call to get the processor affinity for PID pid. The plpa_cpu_set_t type may be manipulated with the PLPA_CPU_* macros (described below). Note that the PLPA guarantees to provide meaningful information in the entire CPU set provided by the user, even if it is larger than the kernel will fill in (e.g., high-order bits that the kernel will not fill in will be zeroed out). Additional error checking is performed in the PLPA; the following values may be returned:
  • 0: Success.
  • EINVAL: One of the following occurred:
    • The CPU set size provided was too small.
    • The CPU set pointer was NULL.
    • PLPA was unable to determine the processor affinity API used on this system; call plpa_api_probe() for more information.

  • ENOSYS: Processor affinity is not supported on this system.

• PLPA_CPU_ZERO(cpuset): This macro zeros out the CPU set pointed to by the cpuset argument.
• PLPA_CPU_SET(num, cpuset): This macro sets bit num in the CPU set pointed to by the cpuset argument.
• PLPA_CPU_CLR(num, cpuset): This macro clears bit num in the CPU set pointed to by the cpuset argument.
• PLPA_CPU_ISSET(num, cpuset): This macro returns the value of the bit num in the CPU set pointed to by the cpuset argument -- either 0 or 1.

Yes.

The PLPA was specifically designed to be safely included in other software projects. The PLPA provides an M4 macro file suitable for acinclude'ing in a top-level configure script, and also has a name-shifting mechanism for its API so that if multiple libraries include name-shifted versions of the PLPA, there will be no symbol conflicts.

The PLPA uses the syscall() interface to bypass GLibc and directly call the get and set affinity functions in the Linux kernel. This is because the GLibc API has changed multiple times, and there are buggy versions in real linux distributions that cause problems. Bypassing it and directly callign the kernel seemed the safest route.

But even so, the kernel has slightly changed its API a few times. Mostly, this has to deal with the len parameter (telling the kernel how long the CPU set argument it). Careful examiniation of the kernel source code has led to a fairly small number of safe tests that can be performed to determine which size it expects.

The PLPA hides all this from the user -- it will figure out what size the kernel expects and use it in all the syscall() interactions with the set and get affinity functions.