diff options
Diffstat (limited to 'plpa-1.3.2/src/libplpa/plpa.h')
-rw-r--r-- | plpa-1.3.2/src/libplpa/plpa.h | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/plpa-1.3.2/src/libplpa/plpa.h b/plpa-1.3.2/src/libplpa/plpa.h new file mode 100644 index 0000000..2bd21a5 --- /dev/null +++ b/plpa-1.3.2/src/libplpa/plpa.h @@ -0,0 +1,299 @@ +/* plpa-1.3.2/src/libplpa/plpa.h. Generated from plpa.h.in by configure. */ +/* -*- c -*- + * + * Copyright (c) 2004-2005 The Trustees of Indiana University. + * All rights reserved. + * Copyright (c) 2004-2005 The Regents of the University of California. + * All rights reserved. + * Copyright (c) 2006-2008 Cisco, Inc. All rights reserved. + * $COPYRIGHT$ + * + * Additional copyrights may follow + * + * $HEADER$ + */ + +/* + * Some notes about the declarations and definitions in this file: + * + * This file is a mix of internal and public declarations. + * Applications are warned against using the internal types; they are + * subject to change with no warning. + * + * The PLPA_NAME() and PLPA_NAME_CAPS() macros are used for prefixing + * the PLPA type names, enum names, and symbol names when embedding + * PLPA. When not embedding, the default prefix is "plpa_" (or + * "PLPA_" when using PLPA_NAME_CAPS()). Hence, if you see a + * declaration like this: + * + * int PLPA_NAME(foo)(void); + * + * It's a function named plpa_foo() that returns an int and takes no + * arguments when building PLPA as a standalone library. It's a + * function with a different prefix than "plpa_" when the + * --enable-included-mode and --with-plpa-symbol-prefix options are + * supplied to PLPA's configure script. + * + * Note that this header file differentiates between a + * processor/socket/core ID and a processor/socket/core number. The + * "ID" is the integer that is used by Linux to identify that entity. + * These integers may or may not be contiguous. The "number" is a + * contiguous set of integers starting with 0 and going to (count-1), + * where (count) is the number of processors, sockets, and cores + * (where the count of cores is dependent upon the socket). Hence, + * "number" is a human convenience, and "ID" is the actual Linux + * identifier. + */ + +#ifndef PLPA_H +#define PLPA_H + +/* Absolutely must not include <sched.h> here or it will generate + conflicts. */ + +/* For memset() */ +#include <string.h> +/* For pid_t and size_t */ +#include <sys/types.h> + +/*************************************************************************** + * Internal types + ***************************************************************************/ + +/* If we're building PLPA itself, <plpa_config.h> will have already + been included. But <plpa_config.h> is a private header file; it is + not installed into $includedir. Hence, applications including + <plpa.h> will not have included <plpa_config.h> (this is by + design). So include just enough information here to allow us to + continue. */ +#ifndef PLPA_CONFIG_H +/* The PLPA symbol prefix */ +#define PLPA_SYM_PREFIX plpa_ + +/* The PLPA symbol prefix in all caps */ +#define PLPA_SYM_PREFIX_CAPS PLPA_ +#endif + +/* Preprocessors are fun -- the double inderection is unfortunately + necessary. */ +#define PLPA_MUNGE_NAME(a, b) PLPA_MUNGE_NAME2(a, b) +#define PLPA_MUNGE_NAME2(a, b) a ## b +#define PLPA_NAME(name) PLPA_MUNGE_NAME(PLPA_SYM_PREFIX, name) +#define PLPA_NAME_CAPS(name) PLPA_MUNGE_NAME(PLPA_SYM_PREFIX_CAPS, name) + +/*************************************************************************** + * Public type + ***************************************************************************/ + +/* Values that can be returned from plpa_api_probe() */ +typedef enum { + /* Sentinel value */ + PLPA_NAME_CAPS(PROBE_UNSET), + /* sched_setaffinity syscall available */ + PLPA_NAME_CAPS(PROBE_OK), + /* syscall unavailable/unimplemented */ + PLPA_NAME_CAPS(PROBE_NOT_SUPPORTED), + /* we experienced some strange failure that the user should report */ + PLPA_NAME_CAPS(PROBE_UNKNOWN) +} PLPA_NAME(api_type_t); + +/*************************************************************************** + * Internal types + ***************************************************************************/ + +/* Internal PLPA bitmask type. This type should not be used by + external applications! */ +typedef unsigned long int PLPA_NAME(bitmask_t); +#define PLPA_BITMASK_T_NUM_BITS (sizeof(PLPA_NAME(bitmask_t)) * 8) +#define PLPA_BITMASK_CPU_MAX 1024 +#define PLPA_BITMASK_NUM_ELEMENTS (PLPA_BITMASK_CPU_MAX / PLPA_BITMASK_T_NUM_BITS) + +/*************************************************************************** + * Public type + ***************************************************************************/ + +/* Public type for the PLPA cpu set. */ +typedef struct { PLPA_NAME(bitmask_t) bitmask[PLPA_BITMASK_NUM_ELEMENTS]; } PLPA_NAME(cpu_set_t); + +/*************************************************************************** + * Internal macros + ***************************************************************************/ + +/* Internal macro for identifying the byte in a bitmask array. This + macro should not be used by external applications! */ +#define PLPA_CPU_BYTE(num) ((num) / PLPA_BITMASK_T_NUM_BITS) + +/* Internal macro for identifying the bit in a bitmask array. This + macro should not be used by external applications! */ +#define PLPA_CPU_BIT(num) ((num) % PLPA_BITMASK_T_NUM_BITS) + +/*************************************************************************** + * Public macros + ***************************************************************************/ + +/* Public macro to zero out a PLPA cpu set (analogous to the FD_ZERO() + macro; see select(2)). */ +#define PLPA_CPU_ZERO(cpuset) \ + memset((cpuset), 0, sizeof(PLPA_NAME(cpu_set_t))) + +/* Public macro to set a bit in a PLPA cpu set (analogous to the + FD_SET() macro; see select(2)). */ +#define PLPA_CPU_SET(num, cpuset) \ + (cpuset)->bitmask[PLPA_CPU_BYTE(num)] |= ((PLPA_NAME(bitmask_t))1 << PLPA_CPU_BIT(num)) + +/* Public macro to clear a bit in a PLPA cpu set (analogous to the + FD_CLR() macro; see select(2)). */ +#define PLPA_CPU_CLR(num, cpuset) \ + (cpuset)->bitmask[PLPA_CPU_BYTE(num)] &= ~((PLPA_NAME(bitmask_t))1 << PLPA_CPU_BIT(num)) + +/* Public macro to test if a bit is set in a PLPA cpu set (analogous + to the FD_ISSET() macro; see select(2)). */ +#define PLPA_CPU_ISSET(num, cpuset) \ + (0 != (((cpuset)->bitmask[PLPA_CPU_BYTE(num)]) & ((PLPA_NAME(bitmask_t))1 << PLPA_CPU_BIT(num)))) + +/*************************************************************************** + * Public functions + ***************************************************************************/ + +/* Setup PLPA internals. This function is optional; it will be + automatically invoked by all the other API functions if you do not + invoke it explicitly. Returns 0 upon success. */ +int PLPA_NAME(init)(void); + +/* Check what API is on this machine. If api_type returns + PLPA_PROBE_OK, then PLPA can function properly on this machine. + Returns 0 upon success. */ +int PLPA_NAME(api_probe)(PLPA_NAME(api_type_t) *api_type); + +/* Set processor affinity. Use the PLPA_CPU_* macros to set the + cpuset value. The same rules and restrictions about pid apply as + they do for the sched_setaffinity(2) system call. Bits set in the + CPU mask correspond to Linux processor IDs. Returns 0 upon + success. */ +int PLPA_NAME(sched_setaffinity)(pid_t pid, size_t cpusetsize, + const PLPA_NAME(cpu_set_t) *cpuset); + +/* Get processor affinity. Use the PLPA_CPU_* macros to analyze the + returned value of cpuset. The same rules and restrictions about + pid apply as they do for the sched_getaffinity(2) system call. + Bits set in the CPU mask corresopnd to Linux processor IDs. + Returns 0 upon success. */ +int PLPA_NAME(sched_getaffinity)(pid_t pid, size_t cpusetsize, + PLPA_NAME(cpu_set_t) *cpuset); + +/* Return whether topology information is available (i.e., + plpa_map_to_*, plpa_max_*). The topology functions will be + available if supported == 1 and the function returns 0. */ +int PLPA_NAME(have_topology_information)(int *supported); + +/* Map (socket_id,core_id) tuple to virtual processor ID. processor_id is + then suitable for use with the PLPA_CPU_* macros, probably leading + to a call to plpa_sched_setaffinity(). Returns 0 upon success. */ +int PLPA_NAME(map_to_processor_id)(int socket_id, int core_id, + int *processor_id); + +/* Map processor_id to (socket_id,core_id) tuple. The processor_id input is + usually obtained from the return from the plpa_sched_getaffinity() + call, using PLPA_CPU_ISSET to find individual bits in the map that + were set/unset. plpa_map_to_socket_core() can map the bit indexes + to a socket/core tuple. Returns 0 upon success. */ +int PLPA_NAME(map_to_socket_core)(int processor_id, + int *socket_id, int *core_id); + +/* This function is deprecated and will disappear in a future release. + It is exactly equivalent to calling + plpa_get_processor_data(PLPA_COUNT_ALL, num_processors, + max_processor_id). */ +int PLPA_NAME(get_processor_info)(int *num_processors, int *max_processor_id); + +/* Typedefs for specifying which processors / sockets / cores to count + in get_processor_data() and get_processor_id() */ +typedef enum { + /* Only count online processors */ + PLPA_NAME_CAPS(COUNT_ONLINE), + /* Only count offline processors */ + PLPA_NAME_CAPS(COUNT_OFFLINE), + /* Count all processors (online and offline) */ + PLPA_NAME_CAPS(COUNT_ALL) +} PLPA_NAME(count_specification_t); + +/* Returns both the number of processors in a system and the maximum + Linux virtual processor ID (because it may be higher than the + number of processors if there are "holes" in the available Linux + virtual processor IDs). The count_spec argument specifies whether + to count all processors, only online processors, or only offline + processors. Returns 0 upon success. */ +int PLPA_NAME(get_processor_data)(PLPA_NAME(count_specification_t) count_spec, + int *num_processors, int *max_processor_id); + +/* Returns the Linux processor ID for the Nth processor. For example, + if the Linux processor IDs have "holes", use this function to say + "give me the Linux processor ID of the 4th processor." count_spec + specifies whether to count online, offline, or all processors when + looking for the processor_num'th processor. Returns 0 upon + success. */ +int PLPA_NAME(get_processor_id)(int processor_num, + PLPA_NAME(count_specification_t) count_spec, + int *processor_id); + +/* Check to see if a given Linux processor ID exists / is online. + Returns 0 on success. */ +int PLPA_NAME(get_processor_flags)(int processor_id, int *exists, int *online); + +/* Returns both the number of sockets in the system and the maximum + socket ID number (in case there are "holes" in the list of available + socket IDs). Returns 0 upon sucess. */ +int PLPA_NAME(get_socket_info)(int *num_sockets, int *max_socket_id); + +/* Returns the Linux socket ID for the Nth socket. For example, if + the socket IDs have "holes", use this function to say "give me the + Linux socket ID of the 2nd socket." Linux does not specify the + socket/core tuple information for offline processors, so a + plpa_count_specification_t parameter is not used here. Returns 0 + upon success. */ +int PLPA_NAME(get_socket_id)(int socket_num, int *socket_id); + +/* Return both the number of cores and the max code ID for a given + socket (in case there are "holes" in the list of available core + IDs). Returns 0 upon success. */ +int PLPA_NAME(get_core_info)(int socket_id, int *num_cores, int *max_core_id); + +/* Given a specific socket, returns the Linux core ID for the Nth + core. For example, if the core IDs have "holes", use this function + to say "give me the Linux core ID of the 4th core on socket ID 7." + Linux does not specify the socket/core tuple information for + offline processors, so a plpa_count_specification_t parameter is + not used here. Returns 0 upon success. Returns 0 upon success. */ +int PLPA_NAME(get_core_id)(int socket_id, int core_num, int *core_id); + +/* Check to see if a given Linux (socket_id,core_id) tuple exists / is + online. Returns 0 on success. */ +int PLPA_NAME(get_core_flags)(int socket_id, int core_id, + int *exists, int *online); + +/* Typedefs for specifying the cache behavior via + plpa_set_cache_behavior() */ +typedef enum { + /* Use the cache (default behavior); fills the cache right now if + it's not already full */ + PLPA_NAME_CAPS(CACHE_USE), + /* Never use the cache; always look up the information in + the kernel */ + PLPA_NAME_CAPS(CACHE_IGNORE), + /* Refresh the cache right now */ + PLPA_NAME_CAPS(CACHE_REFRESH) +} PLPA_NAME(cache_behavior_t); + +/* Set PLPA's cache behavior. Returns 0 upon success. */ +int PLPA_NAME(set_cache_behavior)(PLPA_NAME(cache_behavior_t)); + +/* Shut down PLPA. This function releases resources used by the PLPA. + It should be the last PLPA function invoked, or can be used to + forcibly cause PLPA to dump its topology cache and re-analyze the + underlying system the next time another PLPA function is called. + Specifically: it is safe to call plpa_init() (or any other PLPA + function) again after plpa_finalized(). Returns 0 upon success. */ +int PLPA_NAME(finalize)(void); + +#endif /* PLPA_H */ + |