Merge release-4-6 into master

[alexxy/gromacs.git] / src / gromacs / legacyheaders / gmx_cpuid.h

diff --git a/src/gromacs/legacyheaders/gmx_cpuid.h b/src/gromacs/legacyheaders/gmx_cpuid.h
index 25c42e1db2c7a720a635e747fd515384110e5192..6fe60f824780b5edbda95cd865103d0b1fc24dcc 100644 (file)
--- a/src/gromacs/legacyheaders/gmx_cpuid.h
+++ b/src/gromacs/legacyheaders/gmx_cpuid.h
@@ -23,6 +23,7 @@
 
 #include <stdio.h>
 
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -173,6 +174,39 @@ gmx_cpuid_feature           (gmx_cpuid_t                cpuid,
                              enum gmx_cpuid_feature     feature);
 
 
+/* Return pointers to cpu topology information.
+ * 
+ * Important: CPU topology requires more OS support than most other
+ * functions in this file, including support for thread pinning to hardware.
+ * This means it will not work on some platforms, including e.g. Mac OS X.
+ * Thus, it is IMPERATIVE that you check the return value from this routine
+ * before doing anything with the information. It is only if the return
+ * value is zero that the data is valid.
+ *
+ * For the returned values we have:
+ * - nprocessors         Total number of logical processors reported by OS
+ * - npackages           Usually number of CPU sockets
+ * - ncores_per_package  Number of cores in each package
+ * - nhwthreads_per_core Number of hardware threads per core; 2 for hyperthreading.
+ * - package_id          Array with the package index for each logical cpu
+ * - core_id             Array with local core index for each logical cpu
+ * - hwthread_id         Array with local hwthread index for each logical cpu
+ * - locality_order      Array with logical cpu numbers, sorted in order
+ *                       of physical and logical locality in the system.
+ *
+ * All arrays are of length nprocessors.
+ */
+int
+gmx_cpuid_topology(gmx_cpuid_t        cpuid,
+                   int *              nprocessors,
+                   int *              npackages,
+                   int *              ncores_per_package,
+                   int *              nhwthreads_per_core,
+                   const int **       package_id,
+                   const int **       core_id,
+                   const int **       hwthread_id,
+                   const int **       locality_order);
+
 /* Enumerated values for x86 SMT enabled-status. Note that this does not refer
  * to Hyper-Threading support (that is the flag GMX_CPUID_FEATURE_X86_HTT), but
  * whether Hyper-Threading is _enabled_ and _used_ in bios right now.
@@ -211,12 +245,14 @@ enum gmx_cpuid_x86_smt
  * in order not to give the impression we can detect any SMT. We haven't
  * even tested the performance on other SMT implementations, so it is not
  * obvious we shouldn't use SMT there.
+ *
+ * Note that you can get more complete topology information from
+ * gmx_cpuid_topology(), although that requires slightly more OS support.
  */
 enum gmx_cpuid_x86_smt
 gmx_cpuid_x86_smt(gmx_cpuid_t cpuid);
 
 
-
 /* Formats a text string (up to n characters) from the data structure.
  * The output will have max 80 chars between newline characters.
  */