Commit 2a123830 authored by Pavan Balaji's avatar Pavan Balaji
Browse files

[svn-r9030] Upgrade hwloc to 1.3rc2.

parent 3ed4ffc4
......@@ -9,7 +9,7 @@
functions is: MPIX_Ibcast, MPIX_Ibarrier, MPIX_Ireduce, MPIX_Ialltoallv,
MPIX_Iallreduce.
# PM/PMI: Upgrade hwloc to 1.3rc1.
# PM/PMI: Upgrade hwloc to 1.3rc2.
===============================================================================
......
......@@ -33,6 +33,15 @@ Version 1.3.0
and configuration.
+ Allow user-given distance matrices to remove or replace those
discovered by the OS backend.
* XML improvements
+ XML is now always supported: a minimalistic custom import/export
code is used when libxml2 is not available. It is only guaranteed
to read XML files generated by hwloc.
+ hwloc_topology_export_xml() and export_xmlbuffer() now return an
integer.
+ Add hwloc_free_xmlbuffer() to free the buffer allocated by
hwloc_topology_export_xmlbuffer().
+ Hide XML topology error messages unless HWLOC_XML_VERBOSE=1.
* Minor API updates
+ Add hwloc_obj_add_info to customize object info attributes.
* Tools
......@@ -44,6 +53,21 @@ Version 1.3.0
+ Add --whole-system option to hwloc-ps.
Version 1.2.2
-------------
* Fix build on AIX 5.2, thanks Utpal Kumar Ray for the report.
* Fix XML import of very large page sizes or counts on 32bits platform,
thanks to Karsten Hopp for the RedHat ticket.
* Fix crash when administrator limitations such as Linux cgroup require
to restrict distance matrices. Thanks to Ake Sandgren for reporting the
problem.
* Fix the removal of objects such as AMD Magny-Cours dual-node sockets
in case of administrator restrictions.
* Improve error reporting and messages in case of wrong synthetic topology
description.
* Several other minor internal fixes and documentation improvements.
Version 1.2.1
-------------
* Improve support of AMD Bulldozer "Compute-Unit" modules by detecting
......
......@@ -16,7 +16,7 @@ release=0
# requirement is that it must be entirely printable ASCII characters
# and have no white space.
greek=rc1
greek=rc2
# If want_repo_rev=1, then the SVN r number will be included in the overall
# hwloc version number in some form.
......
......@@ -605,24 +605,24 @@ EOF])
fi
HWLOC_CFLAGS="$HWLOC_CFLAGS $HWLOC_PCI_CFLAGS"
# XML support
hwloc_xml_happy=
if test "x$enable_xml" != "xno"; then
HWLOC_PKG_CHECK_MODULES([XML], [libxml-2.0], [xmlNewDoc],
[hwloc_xml_happy=yes],
[hwloc_xml_happy=no])
# libxml2 support
hwloc_libxml2_happy=
if test "x$enable_libxml2" != "xno"; then
HWLOC_PKG_CHECK_MODULES([LIBXML2], [libxml-2.0], [xmlNewDoc],
[hwloc_libxml2_happy=yes],
[hwloc_libxml2_happy=no])
fi
if test "x$hwloc_xml_happy" = "xyes"; then
if test "x$hwloc_libxml2_happy" = "xyes"; then
HWLOC_REQUIRES="libxml-2.0 $HWLOC_REQUIRES"
AC_DEFINE([HWLOC_HAVE_XML], [1], [Define to 1 if you have the `xml' library.])
AC_SUBST([HWLOC_HAVE_XML], [1])
AC_DEFINE([HWLOC_HAVE_LIBXML2], [1], [Define to 1 if you have the `libxml2' library.])
AC_SUBST([HWLOC_HAVE_LIBXML2], [1])
else
AC_SUBST([HWLOC_HAVE_XML], [0])
AS_IF([test "$enable_xml" = "yes"],
[AC_MSG_WARN([--enable-xml requested, but XML support was not found])
AC_SUBST([HWLOC_HAVE_LIBXML2], [0])
AS_IF([test "$enable_libxml2" = "yes"],
[AC_MSG_WARN([--enable-libxml2 requested, but libxml2 was not found])
AC_MSG_ERROR([Cannot continue])])
fi
HWLOC_CFLAGS="$HWLOC_CFLAGS $HWLOC_XML_CFLAGS"
HWLOC_CFLAGS="$HWLOC_CFLAGS $HWLOC_LIBXML2_CFLAGS"
# Setup HWLOC's C, CPP, and LD flags, and LIBS
AC_SUBST(HWLOC_REQUIRES)
......@@ -711,7 +711,6 @@ AC_DEFUN([HWLOC_DO_AM_CONDITIONALS],[
AM_CONDITIONAL([HWLOC_HAVE_CUDART],
[test "x$hwloc_have_cudart" = "xyes"])
AM_CONDITIONAL([HWLOC_HAVE_CAIRO], [test "x$enable_cairo" != "xno"])
AM_CONDITIONAL([HWLOC_HAVE_XML], [test "$hwloc_xml_happy" = "yes"])
AM_CONDITIONAL([HWLOC_HAVE_LIBPCI], [test "$hwloc_pci_happy" = "yes"])
AM_CONDITIONAL([HWLOC_HAVE_SET_MEMPOLICY], [test "x$enable_set_mempolicy" != "xno"])
AM_CONDITIONAL([HWLOC_HAVE_MBIND], [test "x$enable_mbind" != "xno"])
......
......@@ -55,10 +55,10 @@ AC_DEFUN([HWLOC_DEFINE_ARGS],[
AS_HELP_STRING([--disable-cairo],
[Disable the Cairo back-end of hwloc's lstopo command]))
# XML?
AC_ARG_ENABLE([xml],
AS_HELP_STRING([--disable-xml],
[Disable the XML back-end of hwloc's lstopo command]))
# XML using libxml2?
AC_ARG_ENABLE([libxml2],
AS_HELP_STRING([--disable-libxml2],
[Do not use libxml2 for XML support, use a custom minimalistic support]))
# PCI?
AC_ARG_ENABLE([pci],
......@@ -369,9 +369,7 @@ EOF
hwloc_have_cudart=yes])],
[AC_MSG_RESULT(no)])])
if test "x$enable_xml" != "xno"; then
AC_CHECK_PROGS(XMLLINT, [xmllint])
fi
AC_CHECK_PROGS(XMLLINT, [xmllint])
AC_CHECK_PROGS(BUNZIPP, bunzip2, false)
......
......@@ -39,7 +39,7 @@ debug=
want_success_mail=1
# max length of logfile to send in an e-mail
max_log_len=999999
max_log_len=50
# how many snapshots to keep in the destdir?
max_snapshots=5
......
......@@ -367,7 +367,8 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_cudart_get_device_cpuset.3 \
$(DOX_MAN_DIR)/man3/hwloc_distribute.3 \
$(DOX_MAN_DIR)/man3/hwloc_distributev.3 \
$(DOX_MAN_DIR)/man3/hwloc_free.3 \
$(DOX_MAN_DIR)/man3/hwloc_free.3 \
$(DOX_MAN_DIR)/man3/hwloc_free_xmlbuffer.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_ancestor_obj_by_depth.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_ancestor_obj_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_api_version.3 \
......
......@@ -141,9 +141,12 @@ and build.
The hwloc core may also benefit from the following development packages:
<ul>
<li>libxml2 for XML import/export (also needed for lstopo XML support).</li>
<li>pciutils (libpci) for I/O discovery.</li>
<li>libnuma for memory binding and migration support on Linux.</li>
<li>libxml2 for full XML import/export support (otherwise, the
internal minimalistic parser will only be able to import
XML files that were exported by the same hwloc release).
See \ref xml for details.</li>
</ul>
......@@ -421,7 +424,7 @@ low-level routines for advanced programmers that want to manually
manipulate objects and follow links between them. Documentation for
everything in hwloc.h are provided later in this document. Developers
should also look at hwloc/helper.h (and also in this document, which
provides good higher-level topology traversal examples.
provides good higher-level topology traversal examples).
To precisely define the vocabulary used by hwloc, a \ref termsanddefs
section is available and should probably be read first.
......@@ -627,6 +630,7 @@ The documentation chapters include
<li> \ref envvar
<li> \ref cpu_mem_bind
<li> \ref iodevices
<li> \ref xml
<li> \ref interoperability
<li> \ref threadsafety
<li> \ref embed
......@@ -712,14 +716,14 @@ Make sure to have had a look at those too!
<dd>The index that the operating system (OS) uses to identify the
object. This may be completely arbitrary, non-unique, non-contiguous, not
representative of logical proximity, and may depend on the BIOS
configuration. That is why hwloc almost never use them, only in the default
configuration. That is why hwloc almost never uses them, only in the default
lstopo output (<tt>P#x</tt>) and cpuset masks.</dd>
<dt>Logical index</dt>
<dd>Index to uniquely identify objects of the same type and depth,
automatically computed by hwloc according to the topology. It expresses
logical proximity in a generic way, i.e. objects which have adjacent logical
indexes are adjacent in the topology. That is why hwloc almost always use
indexes are adjacent in the topology. That is why hwloc almost always uses
it in its API, since it expresses logical proximity. They can be shown (as
<tt>L#x</tt>) by <tt>lstopo</tt> thanks to the <tt>-l</tt> option. This index
is always linear and in
......@@ -848,6 +852,15 @@ following environment variables.
return success. To have hwloc still actually call OS-specific hooks,
HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that
the loaded file is really the underlying system.
See also \ref xml.
</dd>
<dt>HWLOC_XML_VERBOSE=1</dt>
<dd>enable verbose messages in the XML or synthetic topology backends.
hwloc XML backends (see \ref xml) can emit some error messages to
the error output stream.
Enabling these verbose messages within hwloc can be useful for
understanding failures to parse input XML topologies.
</dd>
<dt>HWLOC_FSROOT=/path/to/linux/filesystem-root/</dt>
......@@ -1183,6 +1196,61 @@ Machine (24GB)
\page xml Importing and exporting topologies from/to XML files
hwloc offers the ability to export topologies to XML files and reload
them later. This is for instance useful for loading topologies faster
(see \ref faq_xml), manipulating other nodes' topology, or avoiding
the need for privileged processes (see \ref faq_privileged).
Topologies may be exported to XML files thanks to hwloc_topology_export_xml(),
or to a XML memory buffer with hwloc_topology_export_xmlbuffer().
The lstopo program can also serve as a XML topology export tool.
XML topologies may then be reloaded later with hwloc_topology_set_xml()
and hwloc_topology_set_xmlbuffer().
The XMLFILE environment variable also tells hwloc to load the topology
from the given XML file.
\section xml_backends libxml2 and minimalistic XML backends
hwloc offers two backends for importing/exporting XML.
First, it can use the libxml2 library for importing/exporting XML
files. It features full XML support, for instance when those files
have to be manipulated by non-hwloc software (e.g. a XSLT parser).
The libxml2 backend is enabled by default if libxml2 development
headers are available.
If libxml2 is not available at configure time,
or if <tt>--disable-libxml2</tt> is passed, hwloc falls back to a
custom backend.
Contrary to the aforementioned full XML backend with libxml2, this
minimalistic XML backend cannot be guaranteed to work with external
programs.
It should only be assumed to be compatible with the same hwloc
release (even if using the libxml2 backend).
Its advantage is however to always be available without requiring
any external dependency.
\section xml_errors XML import error management
Importing XML files can fail at least because of file access errors,
invalid XML syntax or non-hwloc-valid XML contents.
Both backend cannot detect all these errors when the input XML
file or buffer is selected (when hwloc_topology_set_xml() or
hwloc_topology_set_xmlbuffer() is called).
Some errors such non-hwloc-valid contents can only be detected
later when loading the topology with hwloc_topology_load().
It is therefore strongly recommended to check the return value of
both hwloc_topology_set_xml() (or hwloc_topology_set_xmlbuffer())
and hwloc_topology_load() to handle all these errors.
\page interoperability Interoperability With Other Software
Although hwloc offers its own portable interface, it still may have to
......@@ -1515,6 +1583,7 @@ files or calling multiple functions of the operating system.
It is also possible to manipulate such XML files with the C programming
interface, and the import/export may also be directed to memory buffer
(that may for instance be transmitted between applications through a socket).
See also \ref xml.
\section faq_privileged Does hwloc require privileged access?
......@@ -1528,7 +1597,8 @@ and the entire PCI discovery on FreeBSD requires access to the
To workaround this limitation, it is recommended to export the
topology as a XML file generated by the administrator (with the
lstopo program) and make it available to all users.
lstopo program) and make it available to all users
(see \ref xml).
It will offer all discovery information to any application without
requiring any privileged access anymore.
Only the necessary hardware characteristics will be exported, no
......
......@@ -6,6 +6,36 @@
* See COPYING in top-level directory.
*/
/*=====================================================================
* PLEASE GO READ THE DOCUMENTATION!
* ------------------------------------------------
* $tarball_directory/doc/doxygen-doc/
* or
* http://www.open-mpi.org/projects/hwloc/doc/
*=====================================================================
*
* FAIR WARNING: Do NOT expect to be able to figure out all the
* subtleties of hwloc by simply reading function prototypes and
* constant descrptions here in this file.
*
* Hwloc has wonderful documentation in both PDF and HTML formats for
* your reading pleasure. The formal documentation explains a LOT of
* hwloc-specific concepts, provides definitions, and discusses the
* "big picture" for many of the things that you'll find here in this
* header file.
*
* The PDF/HTML documentation was generated via Doxygen; much of what
* you'll see in there is also here in this file. BUT THERE IS A LOT
* THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
*
* There are entire paragraph-length descriptions, discussions, and
* pretty prictures to explain subtle corner cases, provide concrete
* examples, etc.
*
* Please, go read the documentation. :-)
*
*=====================================================================*/
/** \file
* \brief The hwloc API.
*
......@@ -436,7 +466,7 @@ union hwloc_obj_attr_u {
/** \brief Cache-specific Object Attributes */
struct hwloc_cache_attr_s {
hwloc_uint64_t size; /**< \brief Size of cache in bytes */
unsigned depth; /**< \brief Depth of cache */
unsigned depth; /**< \brief Depth of cache (e.g., L1, L2, ...etc.) */
unsigned linesize; /**< \brief Cache-line size in bytes */
int associativity; /**< \brief Ways of associativity,
* -1 if fully associative, 0 if unknown */
......@@ -482,12 +512,12 @@ union hwloc_obj_attr_u {
* containing object is the root object of the topology, then the
* distances are available for all objects in the machine.
*
* The distance may be a memory latency, as defined by the ACPI SLIT
* specification. If so, the \p latency pointer will not be \c NULL
* and the pointed array will contain non-zero values.
* If the \p latency pointer is not \c NULL, the pointed array contains
* memory latencies (non-zero values), as defined by the ACPI SLIT
* specification.
*
* In the future, some other types of distances may be considered.
* In these cases, \p latency will be \c NULL.
* In these cases, \p latency may be \c NULL.
*/
struct hwloc_distances_s {
unsigned relative_depth; /**< \brief Relative depth of the considered objects
......@@ -552,8 +582,15 @@ HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
/** \brief Run internal checks on a topology structure
*
* The program aborts if an inconsistency is detected in the given topology.
*
* \param topology is the topology to be checked
*
* \note This routine is only useful to developers.
*
* \note The input topology should have been previously loaded with
* hwloc_topology_load().
*/
HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
......@@ -688,7 +725,12 @@ HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned
* Not using the main file-system root causes hwloc_topology_is_thissystem()
* to return 0.
*
* \note For conveniency, this backend provides empty binding hooks which just
* Note that this function does not actually load topology
* information; it just tells hwloc where to load it from. You'll
* still need to invoke hwloc_topology_load() to actually load the
* topology information.
*
* \note For convenience, this backend provides empty binding hooks which just
* return success. To have hwloc still actually call OS-specific hooks, the
* HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
* file is really the underlying system.
......@@ -712,8 +754,8 @@ HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topo
/** \brief Enable synthetic topology.
*
* Gather topology information from the given \p description
* which should be a space-separated string of numbers describing
* Gather topology information from the given \p description,
* a space-separated string of numbers describing
* the arity of each level.
* Each number may be prefixed with a type and a colon to enforce the type
* of a level. If only some level types are enforced, hwloc will try to
......@@ -724,7 +766,12 @@ HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topo
* configuration, this function returns 0.
* Otherwise -1 is returned and errno is set to EINVAL.
*
* \note For conveniency, this backend provides empty binding hooks which just
* Note that this function does not actually load topology
* information; it just tells hwloc where to load it from. You'll
* still need to invoke hwloc_topology_load() to actually load the
* topology information.
*
* \note For convenience, this backend provides empty binding hooks which just
* return success.
*/
HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
......@@ -735,17 +782,30 @@ HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restric
* Setting the environment variable HWLOC_XMLFILE may also result in this behavior.
* This file may have been generated earlier with lstopo file.xml.
*
* \note For conveniency, this backend provides empty binding hooks which just
* Note that this function does not actually load topology
* information; it just tells hwloc where to load it from. You'll
* still need to invoke hwloc_topology_load() to actually load the
* topology information.
*
* \note For convenience, this backend provides empty binding hooks which just
* return success. To have hwloc still actually call OS-specific hooks, the
* HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
* file is really the underlying system.
*/
HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
/** \brief Enable XML based topology using a memory buffer instead of a file.
/** \brief Enable XML based topology using a memory buffer (instead of
* a file, as with hwloc_topology_set_xml()).
*
* Gather topology information from the XML memory buffer given at \p
* buffer and of length \p size. This buffer may have been filled
* earlier with hwloc_topology_export_xmlbuffer().
*
* Note that this function does not actually load topology
* information; it just tells hwloc where to load it from. You'll
* still need to invoke hwloc_topology_load() to actually load the
* topology information.
*
* Gather topology information from the XML memory buffer given at \p buffer
* and of length \p length.
*/
HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
......@@ -757,6 +817,7 @@ HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restric
* array. The \p distances matrix follows the same order.
* The distance from object i to object j in the i*nbobjs+j.
*
* A single latency matrix may be defined for each type.
* If another distance matrix already exists for the given type,
* either because the user specified it or because the OS offers it,
* it will be replaced by the given one.
......@@ -853,23 +914,31 @@ HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(h
/** \defgroup hwlocality_tinker Tinker with topologies.
/** \defgroup hwlocality_tinker Tinker With Topologies.
* @{
*/
/** \brief Export the topology into an XML file.
*
* This file may be loaded later through hwloc_topology_set_xml().
*
* \return -1 if a failure occured.
*/
HWLOC_DECLSPEC void hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
/** \brief Export the topology into a newly-allocated XML memory buffer.
*
* \p xmlbuffer is allocated by the callee and should be freed with xmlFree later in the caller.
* \p xmlbuffer is allocated by the callee and should be freed with
* hwloc_free_xmlbuffer() later in the caller.
*
* This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().
*
* \return -1 if a failure occured.
*/
HWLOC_DECLSPEC void hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
/** \brief Free a buffer allocated by hwloc_topology_export_xmlbuffer() */
HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
/** \brief Add a MISC object to the topology
*
......@@ -935,8 +1004,13 @@ HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict top
/** \defgroup hwlocality_information Get some Topology Information
/** \defgroup hwlocality_information Get Some Topology Information
* @{
*
* Be sure to see the figure in \ref termsanddefs that shows a
* complete topology tree, including depths, child/sibling/cousin
* relationships, and an example of an asymmetric topology where one
* socket has fewer caches than its peers.
*/
/** \brief Get the depth of the hierarchical tree of objects.
......@@ -980,7 +1054,8 @@ enum hwloc_get_type_depth_e {
*/
HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure;
/** \brief Returns the width of level at depth \p depth */
/** \brief Returns the width of level at depth \p depth.
*/
HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure;
/** \brief Returns the width of level type \p type
......@@ -1014,6 +1089,11 @@ HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restri
/** \defgroup hwlocality_traversal Retrieve Objects
* @{
*
* Be sure to see the figure in \ref termsanddefs that shows a
* complete topology tree, including depths, child/sibling/cousin
* relationships, and an example of an asymmetric topology where one
* socket has fewer caches than its peers.
*/
/** \brief Returns the topology object at logical index \p idx from depth \p depth */
......@@ -1242,24 +1322,30 @@ typedef enum {
* support of CPU bindings, i.e. potentially
* return -1 with errno set to ENOSYS in some
* cases.
*
* This flag is only meaningful when
* used with functions that set the
* CPU binding. It is ignored when
* used with functions that get CPU
* binding information.
*/
} hwloc_cpubind_flags_t;
/** \brief Bind current process or thread on cpus given in bitmap \p set
/** \brief Bind current process or thread on cpus given in bitmap \p set.
*
* \return -1 with errno set to ENOSYS if the action is not supported
* \return -1 with errno set to EXDEV if the binding cannot be enforced
*/
HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
/** \brief Get current process or thread binding
/** \brief Get current process or thread binding.
*
* Writes into \p set the cpuset which the process or thread (according to \e
* flags) was last bound to.
*/
HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
/** \brief Bind a process \p pid on cpus given in bitmap \p set
/** \brief Bind a process \p pid on cpus given in bitmap \p set.
*
* \note hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows
* platforms
......@@ -1268,17 +1354,21 @@ HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t s
*/
HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
/** \brief Get the current binding of process \p pid
/** \brief Get the current binding of process \p pid.
*
* \note hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows
* platforms
*
* \note HWLOC_CPUBIND_THREAD can not be used in \p flags.
*
* \note As a special case on Linux, if a tid (thread ID) is supplied
* instead of a pid (process ID), the binding for that specific thread
* is returned.
*/
HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
#ifdef hwloc_thread_t
/** \brief Bind a thread \p thread on cpus given in bitmap \p set
/** \brief Bind a thread \p thread on cpus given in bitmap \p set.
*
* \note hwloc_thread_t is pthread_t on unix platforms, and HANDLE on native
* Windows platforms
......@@ -1289,7 +1379,7 @@ HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thr
#endif
#ifdef hwloc_thread_t
/** \brief Get the current binding of thread \p tid
/** \brief Get the current binding of thread \p tid.
*
* \note hwloc_thread_t is pthread_t on unix platforms, and HANDLE on native
* Windows platforms
......@@ -1316,6 +1406,10 @@ HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_
* outdated.
*
* \note HWLOC_CPUBIND_THREAD can not be used in \p flags.
*
* \note As a special case on Linux, if a tid (thread ID) is supplied
* instead of a pid (process ID), the binding for that specific thread
* is returned.
*/
HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
......
......@@ -28,6 +28,11 @@ extern "C" {
/** \defgroup hwlocality_helper_types Object Type Helpers
* @{
*
* Be sure to see the figure in \ref termsanddefs that shows a
* complete topology tree, including depths, child/sibling/cousin
* relationships, and an example of an asymmetric topology where one
* socket has fewer caches than its peers.
*/
/** \brief Returns the depth of objects of type \p type or below
......@@ -82,6 +87,11 @@ hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
/** \defgroup hwlocality_helper_traversal_basic Basic Traversal Helpers
* @{
*
* Be sure to see the figure in \ref termsanddefs that shows a
* complete topology tree, including depths, child/sibling/cousin
* relationships, and an example of an asymmetric topology where one
* socket has fewer caches than its peers.
*/
/** \brief Returns the top-object of the topology-tree.
......@@ -514,6 +524,11 @@ hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute
/** \defgroup hwlocality_helper_traversal Advanced Traversal Helpers
* @{