Commit 87055429 authored by Pavan Balaji's avatar Pavan Balaji
Browse files

[svn-r9005] Upgraded to hwloc-1.3rc1.

parent 4acc562b
......@@ -9,6 +9,8 @@
functions is: MPIX_Ibcast, MPIX_Ibarrier, MPIX_Ireduce, MPIX_Ialltoallv,
MPIX_Iallreduce.
# PM/PMI: Upgrade hwloc to 1.3rc1.
===============================================================================
Changes in 1.4.1
......
......@@ -17,6 +17,33 @@ bug fixes (and other actions) for each version of hwloc since version
in v0.9.1).
Version 1.3.0
-------------
* Major features
+ Add I/O devices and bridges to the topology using the pciutils
library. Only enabled after setting the relevant flag with
hwloc_topology_set_flags() before hwloc_topology_load(). See the
I/O Devices section in the documentation for details.
* Discovery improvements
+ Add associativity to the cache attributes.
+ Add support for s390/z11 "books" on Linux.
+ Add the HWLOC_GROUPING_ACCURACY environment variable to relax
distance-based grouping constraints. See the Environment Variables
section in the documentation for details about grouping behavior
and configuration.
+ Allow user-given distance matrices to remove or replace those
discovered by the OS backend.
* Minor API updates
+ Add hwloc_obj_add_info to customize object info attributes.
* Tools
+ lstopo now displays I/O devices by default. Several options are
added to configure the I/O discovery.
+ hwloc-calc and hwloc-bind now accept I/O devices as input.
+ Add --restrict option to hwloc-calc and hwloc-distribute.
+ Add --sep option to change the output field separator in hwloc-calc.
+ Add --whole-system option to hwloc-ps.
Version 1.2.1
-------------
* Improve support of AMD Bulldozer "Compute-Unit" modules by detecting
......
......@@ -2,10 +2,10 @@ Introduction
hwloc provides command line tools and a C API to obtain the hierarchical map of
key computing elements, such as: NUMA memory nodes, shared caches, processor
sockets, processor cores, and processing units (logical processors or
"threads"). hwloc also gathers various attributes such as cache and memory
information, and is portable across a variety of different operating systems
and platforms.
sockets, processor cores, processing units (logical processors or "threads")
and even I/O devices. hwloc also gathers various attributes such as cache and
memory information, and is portable across a variety of different operating
systems and platforms.
hwloc primarily aims at helping high-performance computing (HPC) applications,
but is also applicable to any project seeking to exploit code and/or data
......@@ -32,6 +32,16 @@ hwloc supports the following operating systems:
* HP-UX
* Microsoft Windows
Since it uses standard Operating System information, hwloc's support is mostly
independant from the processor type (x86, powerpc, ...) and just relies on the
Operating System support. The only exception to this is kFreeBSD, which does
not support topology information, and hwloc thus uses an x86-only CPUID-based
backend (which could be used for other OSes too).
To check whether hwloc works on a particular machine, just try to build it and
run lstopo. If some things do not look right (e.g. bogus or missing cache
information), see Questions and Bugs below.
hwloc only reports the number of processors on unsupported operating systems;
no topology information is available.
......@@ -54,6 +64,13 @@ below. It may also be used to binding applications onto certain cores or memory
nodes. Several utility programs are also provided to ease command-line
manipulation of topology objects, binding of processes, and so on.
Perl bindings are available from Bernd Kallies on CPAN:
Python bindings are available from Guy Streeter:
* Fedora RPM and tarball.
* git tree (html).
Installation
hwloc (http://www.open-mpi.org/projects/hwloc/) is available under the BSD
......@@ -81,15 +98,20 @@ shell$ make install
The hwloc command-line tool "lstopo" produces human-readable topology maps, as
mentioned above. It can also export maps to the "fig" file format. Support for
PDF, Postscript, and PNG exporting is provided if the "Cairo" development
package can be found when hwloc is configured and build. Similarly, lstopo's
XML support requires the libxml2 development package.
package can be found when hwloc is configured and build.
The hwloc core may also benefit from the following development packages:
* libxml2 (also needed for lstopo XML support).
* pciutils (libpci) for I/O discovery.
* libnuma for memory binding and migration support on Linux.
CLI Examples
On a 4-socket 2-core machine with hyperthreading, the lstopo tool may show the
following graphical output:
dudley.png
dudley.png
Here's the equivalent output in textual form:
......@@ -193,7 +215,7 @@ line), and only socket #0 is shown for brevity:
On a 4-socket 2-core Opteron NUMA machine, the lstopo tool may show the
following graphical output:
hagrid.png
hagrid.png
Here's the equivalent output in textual form:
......@@ -263,7 +285,7 @@ added and only PU #0 is shown for brevity:
On a 2-socket quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each
socket):
emmett.png
emmett.png
Here's the same output in textual form:
......@@ -381,12 +403,12 @@ interfaces for them are usually available on the supported Operating Systems.
Here's the graphical output from lstopo on this platform when Simultaneous
Multi-Threading (SMT) is enabled:
ppc64-with-smt.png
ppc64-with-smt.png
And here's the graphical output from lstopo on this platform when SMT is
disabled:
ppc64-without-smt.png
ppc64-without-smt.png
Notice that hwloc only sees half the PUs when SMT is disabled. PU #15, for
example, seems to change location from NUMA node #0 to #1. In reality, no PUs
......@@ -403,7 +425,7 @@ Note that upgrading the Linux kernel on the same PPC64 system mentioned above
to 2.6.34, hwloc is able to discover all the topology information. The
following picture shows the entire topology layout when SMT is enabled:
ppc64-full-with-smt.png
ppc64-full-with-smt.png
Developers using the hwloc API or XML output for portable applications should
therefore be extremely careful to not make any assumptions about the structure
......@@ -425,8 +447,9 @@ core of the machine.
/* Example hwloc API program.
*
* Copyright ? 2009-2010 INRIA. All rights reserved.
* Copyright ? 2009-2010 Universit? Bordeaux 1
* Copyright ? 2009-2011 Universit? Bordeaux 1
* Copyright ? 2009-2010 Cisco Systems, Inc. All rights reserved.
* See COPYING in top-level directory.
*
* hwloc-hello.c
*/
......@@ -465,7 +488,7 @@ int main(void)
hwloc_topology_init(&topology);
/* ... Optionally, put detection configuration here to ignore
some objects types, define a synthetic topology, etc....
some objects types, define a synthetic topology, etc....
The default is to detect all the objects of the machine that
the caller is allowed to access. See Configure Topology
......@@ -572,7 +595,7 @@ int main(void)
n = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_NODE);
if (n) {
void *m;
size_t size = 1024*1024;
size = 1024*1024;
obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NODE, n - 1);
m = hwloc_alloc_membind_nodeset(topology, size, obj->nodeset,
......@@ -650,7 +673,10 @@ the most recent version of the BIOS for your machine.
If those things fail, contact us on the mailing list for additional help.
Please attach the output of lstopo after having given the --enable-debug option
to ./configure and rebuilt completely, to get debugging output.
to ./configure and rebuilt completely, to get debugging output. Also attach the
/proc + /sys tarball generated by the installed script hwloc-gather-topology.sh
when submitting problems about Linux, or send the output of kstat cpu_info in
the Solaris case, or the output of sysctl hw in the Darwin or BSD cases.
History / Credits
......@@ -674,6 +700,7 @@ The documentation chapters include
* Command-Line Tools
* Environment Variables
* CPU and Memory Binding Overview
* I/O Devices
* Interoperability With Other Software
* Thread Safety
* Embedding hwloc in Other Software
......@@ -683,5 +710,5 @@ Make sure to have had a look at those too!
-------------------------------------------------------------------------------
Generated on Thu Feb 3 2011 11:06:33 for Hardware Locality (hwloc) by doxygen
1.7.2
Generated on Thu Aug 11 2011 10:45:18 for Hardware Locality (hwloc) by doxygen
1.7.4
......@@ -6,8 +6,8 @@
# <major>.<minor>.<release>. If release is zero, then it is omitted.
major=1
minor=2
release=1
minor=3
release=0
# greek is used for alpha or beta release tags. If it is non-empty,
# it will be appended to the version number. It does not have to be
......@@ -16,7 +16,7 @@ release=1
# requirement is that it must be entirely printable ASCII characters
# and have no white space.
greek=rc3
greek=rc1
# If want_repo_rev=1, then the SVN r number will be included in the overall
# hwloc version number in some form.
......@@ -58,4 +58,4 @@ date="Unreleased developer copy"
# 2. Version numbers are described in the Libtool current:revision:age
# format.
libhwloc_so_version=3:1:3
libhwloc_so_version=4:0:4
......@@ -523,6 +523,88 @@ EOF])
AC_DEFINE([HWLOC_HAVE_PTHREAD_GETTHRDS_NP], 1, `Define to 1 if you have pthread_getthrds_np')
)
# PCI support
hwloc_pci_happy=no
if test "x$enable_pci" != "xno"; then
hwloc_pci_happy=yes
HWLOC_PKG_CHECK_MODULES([PCI], [libpci], [pci_cleanup], [:], [
# manually check pciutils in case a old one without .pc is installed
AC_CHECK_HEADERS([pci/pci.h], [
# try first without -lz, it's not always needed (RHEL5, Debian Etch)
AC_CHECK_LIB([pci], [pci_init], [
HWLOC_PCI_LIBS="-lpci"
], [
# try again with -lz because it's needed sometimes (FC7).
# don't use AC_CHECK_LIB again because the cache would
# return "no" without actually rechecking
AC_MSG_CHECKING([for pci_init in -lpci with -lz])
tmp_save_LIBS=$LIBS
LIBS="-lpci -lz $LIBS"
AC_LINK_IFELSE([AC_LANG_CALL([], [pci_init])],
[HWLOC_PCI_LIBS="-lpci -lz"
HWLOC_PCI_ADDITIONAL_LIBS="-lz"
AC_MSG_RESULT(yes)],
[hwloc_pci_happy=no
AC_MSG_RESULT(no)])
LIBS=$tmp_save_LIBS])
# Also check with pci_lookup_name, because that sometimes
# requires -lresolv (RHEL5.6). don't use AC_CHECK_LIB twice
# because the cache would return "no" without actually rechecking
AC_CHECK_LIB([pci], [pci_lookup_name], [],
[AC_CHECK_LIB([resolv], [inet_ntoa],
[AC_MSG_CHECKING([for pci_lookup_name in -lpci with -lresolv])
tmp_save_LIBS=$LIBS
LIBS="-lpci -lresolv $LIBS $HWLOC_PCI_ADDITIONAL_LIBS"
AC_LINK_IFELSE([AC_LANG_CALL([], [pci_lookup_name])],
[HWLOC_PCI_LIBS="$HWLOC_PCI_LIBS -lresolv"
HWLOC_PCI_ADDITIONAL_LIBS="$HWLOC_PCI_ADDITIONAL_LIBS -lresolv"
AC_MSG_RESULT(yes)],
[hwloc_pci_happy=no
AC_MSG_RESULT(no)])
LIBS=$tmp_save_LIBS],
[hwloc_pci_happy=no])])
], [hwloc_pci_happy=no])
])
fi
AC_SUBST(HWLOC_PCI_LIBS)
# If we asked for pci support but couldn't deliver, fail
AS_IF([test "$enable_pci" = "yes" -a "$hwloc_pci_happy" = "no"],
[AC_MSG_WARN([Specified --enable-pci switch, but could not])
AC_MSG_WARN([find appropriate support])
AC_MSG_ERROR([Cannot continue])])
if test "x$hwloc_pci_happy" = "xyes"; then
AC_CHECK_DECLS([PCI_LOOKUP_NO_NUMBERS],,[:],[[#include <pci/pci.h>]])
AC_CHECK_LIB([pci], [pci_find_cap], [enable_pci_caps=yes], [enable_pci_caps=no], [$HWLOC_PCI_ADDITIONAL_LIBS])
if test "x$enable_pci_caps" = "xyes"; then
AC_DEFINE([HWLOC_HAVE_PCI_FIND_CAP], [1], [Define to 1 if `libpci' has the `pci_find_cap' function.])
fi
AC_MSG_CHECKING(whether struct pci_dev has a device_class field)
AC_TRY_COMPILE([#include <pci/pci.h>],
[int f(struct pci_dev *dev) { return dev->device_class; }],
[pcidev_device_class=yes], [pcidev_device_class=no])
AC_MSG_RESULT([$pcidev_device_class])
if test x$pcidev_device_class = xyes; then
AC_DEFINE([HWLOC_HAVE_PCIDEV_DEVICE_CLASS], [1], [Define to 1 if struct pci_dev has a `device_class' field.])
fi
AC_MSG_CHECKING(whether struct pci_dev has a domain field)
AC_TRY_COMPILE([#include <pci/pci.h>],
[int f(struct pci_dev *dev) { return dev->domain; }],
[pcidev_domain=yes], [pcidev_domain=no])
AC_MSG_RESULT([$pcidev_domain])
if test x$pcidev_domain = xyes; then
AC_DEFINE([HWLOC_HAVE_PCIDEV_DOMAIN], [1], [Define to 1 if struct pci_dev has a `domain' field.])
fi
HWLOC_REQUIRES="libpci $HWLOC_REQUIRES"
AC_DEFINE([HWLOC_HAVE_LIBPCI], [1], [Define to 1 if you have the `libpci' library.])
AC_SUBST([HWLOC_HAVE_LIBPCI], [1])
else
AC_SUBST([HWLOC_HAVE_LIBPCI], [0])
fi
HWLOC_CFLAGS="$HWLOC_CFLAGS $HWLOC_PCI_CFLAGS"
# XML support
hwloc_xml_happy=
if test "x$enable_xml" != "xno"; then
......@@ -630,6 +712,7 @@ AC_DEFUN([HWLOC_DO_AM_CONDITIONALS],[
[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"])
AM_CONDITIONAL([HWLOC_HAVE_BUNZIPP], [test "x$BUNZIPP" != "xfalse"])
......
......@@ -59,6 +59,12 @@ AC_DEFUN([HWLOC_DEFINE_ARGS],[
AC_ARG_ENABLE([xml],
AS_HELP_STRING([--disable-xml],
[Disable the XML back-end of hwloc's lstopo command]))
# PCI?
AC_ARG_ENABLE([pci],
AS_HELP_STRING([--disable-pci],
[Disable the PCI device discovery using libpci]))
])dnl
#-----------------------------------------------------------------------
......
......@@ -156,7 +156,8 @@ path to pkg-config.
_HWLOC_PKG_TEXT
To get pkg-config, see <http://pkg-config.freedesktop.org/>.])],
[$5])
[AC_MSG_RESULT([cannot check without pkg-config])
$5])
else
AC_MSG_RESULT([yes])
......
......@@ -39,7 +39,7 @@ debug=
want_success_mail=1
# max length of logfile to send in an e-mail
max_log_len=50
max_log_len=999999
# how many snapshots to keep in the destdir?
max_snapshots=5
......
......@@ -146,14 +146,16 @@ if HWLOC_DOXYGEN_BROKEN_SHORT_NAMES
-@mv -f $(DOX_DIR)/latex/envvar.tex $(DOX_DIR)/latex/a00003.tex
-@mv -f $(DOX_DIR)/html/cpu_mem_bind.html $(DOX_DIR)/html/a00004.html
-@mv -f $(DOX_DIR)/latex/cpu_mem_bind.tex $(DOX_DIR)/latex/a00004.tex
-@mv -f $(DOX_DIR)/html/interoperability.html $(DOX_DIR)/html/a00005.html
-@mv -f $(DOX_DIR)/latex/interoperability.tex $(DOX_DIR)/latex/a00005.tex
-@mv -f $(DOX_DIR)/html/threadsafety.html $(DOX_DIR)/html/a00006.html
-@mv -f $(DOX_DIR)/latex/threadsafety.tex $(DOX_DIR)/latex/a00006.tex
-@mv -f $(DOX_DIR)/html/embed.html $(DOX_DIR)/html/a00007.html
-@mv -f $(DOX_DIR)/latex/embed.tex $(DOX_DIR)/latex/a00007.tex
-@mv -f $(DOX_DIR)/html/faq.html $(DOX_DIR)/html/a00008.html
-@mv -f $(DOX_DIR)/latex/faq.tex $(DOX_DIR)/latex/a00008.tex
-@mv -f $(DOX_DIR)/html/iodevices.html $(DOX_DIR)/html/a00005.html
-@mv -f $(DOX_DIR)/latex/iodevices.tex $(DOX_DIR)/latex/a00005.tex
-@mv -f $(DOX_DIR)/html/interoperability.html $(DOX_DIR)/html/a00006.html
-@mv -f $(DOX_DIR)/latex/interoperability.tex $(DOX_DIR)/latex/a00006.tex
-@mv -f $(DOX_DIR)/html/threadsafety.html $(DOX_DIR)/html/a00007.html
-@mv -f $(DOX_DIR)/latex/threadsafety.tex $(DOX_DIR)/latex/a00007.tex
-@mv -f $(DOX_DIR)/html/embed.html $(DOX_DIR)/html/a00008.html
-@mv -f $(DOX_DIR)/latex/embed.tex $(DOX_DIR)/latex/a00008.tex
-@mv -f $(DOX_DIR)/html/faq.html $(DOX_DIR)/html/a00009.html
-@mv -f $(DOX_DIR)/latex/faq.tex $(DOX_DIR)/latex/a00009.tex
endif
endif
......@@ -257,19 +259,33 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/HWLOC_MEMBIND_REPLICATE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_MEMBIND_STRICT.3 \
$(DOX_MAN_DIR)/man3/HWLOC_MEMBIND_THREAD.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_BRIDGE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_BRIDGE_HOST.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_BRIDGE_PCI.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_CACHE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_CORE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_GROUP.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_MACHINE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_MISC.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_NODE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OS_DEVICE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_BLOCK.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_DMA.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_GPU.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_NETWORK.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_OPENFABRICS.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_PU.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_PCI_DEVICE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_SOCKET.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_SYSTEM.3 \
$(DOX_MAN_DIR)/man3/HWLOC_OBJ_TYPE_MAX.3 \
$(DOX_MAN_DIR)/man3/HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES.3 \
$(DOX_MAN_DIR)/man3/HWLOC_RESTRICT_FLAG_ADAPT_IO.3 \
$(DOX_MAN_DIR)/man3/HWLOC_RESTRICT_FLAG_ADAPT_MISC.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_IO_BRIDGES.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_IO_DEVICES.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_WHOLE_IO.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TYPE_DEPTH_MULTIPLE.3 \
$(DOX_MAN_DIR)/man3/HWLOC_TYPE_DEPTH_UNKNOWN.3 \
......@@ -327,6 +343,7 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_bitmap_weight.3 \
$(DOX_MAN_DIR)/man3/hwloc_bitmap_xor.3 \
$(DOX_MAN_DIR)/man3/hwloc_bitmap_zero.3 \
$(DOX_MAN_DIR)/man3/hwloc_bridge_covers_pcibus.3 \
$(DOX_MAN_DIR)/man3/hwloc_compare_types.3 \
$(DOX_MAN_DIR)/man3/hwloc_compare_types_e.3 \
$(DOX_MAN_DIR)/man3/hwloc_const_bitmap_t.3 \
......@@ -363,6 +380,7 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_get_cpubind.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_depth_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_first_largest_obj_inside_cpuset.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_hostbridge_by_pcibus.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_largest_objs_inside_cpuset.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_last_cpu_location.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_membind.3 \
......@@ -371,6 +389,7 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_get_nbobjs_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_nbobjs_inside_cpuset_by_depth.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_nbobjs_inside_cpuset_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_bridge.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_child.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_obj_by_depth.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_obj_by_type.3 \
......@@ -378,6 +397,9 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_get_next_obj_covering_cpuset_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_obj_inside_cpuset_by_depth.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_obj_inside_cpuset_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_osdev.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_next_pcidev.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_non_io_ancestor_obj.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_below_array_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_below_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_by_depth.3 \
......@@ -385,6 +407,8 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_covering_cpuset.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_inside_cpuset_by_depth.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_obj_inside_cpuset_by_type.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_pcidev_by_busid.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_pcidev_by_busidstring.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_proc_cpubind.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_proc_last_cpu_location.3 \
$(DOX_MAN_DIR)/man3/hwloc_get_proc_membind.3 \
......@@ -419,9 +443,17 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_obj.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_snprintf.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u_hwloc_bridge_attr_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u_hwloc_cache_attr_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u_hwloc_group_attr_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u_hwloc_osdev_attr_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_attr_u_hwloc_pcidev_attr_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_bridge_type_e.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_bridge_type_t.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_osdev_type_e.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_osdev_type_t.3 \
$(DOX_MAN_DIR)/man3/hwloc_distances_s.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_add_info.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_cpuset_snprintf.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_get_info_by_name.3 \
$(DOX_MAN_DIR)/man3/hwloc_obj_info_s.3 \
......@@ -479,6 +511,7 @@ man3_MANS = \
$(DOX_MAN_DIR)/man3/hwloc_topology_set_distance_matrix.3 \
$(DOX_MAN_DIR)/man3/hwloc_topology_support.3 \
$(DOX_MAN_DIR)/man3/hwloc_topology_t.3 \
$(DOX_MAN_DIR)/man3/hwlocality_advanced_io.3 \
$(DOX_MAN_DIR)/man3/hwlocality_api_version.3 \
$(DOX_MAN_DIR)/man3/hwlocality_bitmap.3 \
$(DOX_MAN_DIR)/man3/hwlocality_configuration.3 \
......
......@@ -19,8 +19,9 @@
hwloc provides command line tools and a C API to obtain the
hierarchical map of key computing elements, such as: NUMA memory
nodes, shared caches, processor sockets, processor cores, and
processing units (logical processors or "threads").
nodes, shared caches, processor sockets, processor cores,
processing units (logical processors or "threads")
and even I/O devices.
hwloc also gathers various attributes such as
cache and memory information, and is portable across a variety of
different operating systems and platforms.
......@@ -55,6 +56,16 @@ and Kerrighed support)</li>
<li>Microsoft Windows</li>
</ul>
Since it uses standard Operating System information, hwloc's support is mostly
independant from the processor type (x86, powerpc, ...) and just relies on the
Operating System support. The only exception to this is kFreeBSD, which does
not support topology information, and hwloc thus uses an x86-only CPUID-based
backend (which could be used for other OSes too).
To check whether hwloc works on a particular machine, just try to build it
and run <tt>lstopo</tt>. If some things do not look right (e.g. bogus or missing
cache information), see \ref bugs below.
hwloc only reports the number of processors on unsupported operating
systems; no topology information is available.
......@@ -80,6 +91,16 @@ onto certain cores or memory nodes. Several utility programs are also
provided to ease command-line manipulation of topology objects,
binding of processes, and so on.
Perl bindings are available from Bernd Kallies
<a href=http://search.cpan.org/~bka/Sys-Hwloc-0.10/>on CPAN:</a>
Python bindings are available from Guy Streeter:
<ul>
<li><a href=http://people.redhat.com/streeter/>Fedora RPM and tarball</a>.</li>
<li><a href=git://git.fedorahosted.org/python-hwloc.git>git tree</a>
(<a href=http://git.fedorahosted.org/git/python-hwloc.git>html</a>).</li>
</ul>
\htmlonly
</div><div class="section" id="installation">
\endhtmlonly
......@@ -116,8 +137,15 @@ The hwloc command-line tool "lstopo" produces human-readable topology
maps, as mentioned above. It can also export maps to the "fig" file
format. Support for PDF, Postscript, and PNG exporting is provided if
the "Cairo" development package can be found when hwloc is configured
and build. Similarly, lstopo's XML support requires the libxml2
development package.
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>
</ul>
\htmlonly
</div><div class="section" id="cli_examples">
......@@ -562,7 +590,11 @@ the most recent version of the BIOS for your machine.
If those things fail, contact us on the mailing list for additional
help. Please attach the output of lstopo after having given the
--enable-debug option to ./configure and rebuilt completely, to get
debugging output.
debugging output. Also attach the <tt>/proc</tt> + <tt>/sys</tt> tarball
generated by the installed script <tt>hwloc-gather-topology.sh</tt>
when submitting problems about Linux, or send the
output of <tt>kstat cpu_info</tt> in the Solaris case, or the output of
<tt>sysctl hw</tt> in the Darwin or BSD cases.
\htmlonly
</div><div class="section" id="credits">
......@@ -594,6 +626,7 @@ The documentation chapters include
<li> \ref tools
<li> \ref envvar
<li> \ref cpu_mem_bind
<li> \ref iodevices
<li> \ref interoperability
<li> \ref threadsafety
<li> \ref embed
......@@ -842,21 +875,54 @@ following environment variables.
backend, but still having binding functions actually do bind.
</dd>
<dt>HWLOC_IGNORE_DISTANCES=0</dt>
<dd>disables objects grouping based on distances.
<dt>HWLOC_HIDE_ERRORS=0</dt>
<dd>enables or disables verbose reporting of errors.
The hwloc library may issue warnings to the standard error stream
when it detects a problem during topology discovery, for instance
if the operating system (or user) gives contradictory topology
information. Setting this environment variable to 1 removes the
actual displaying of these error messages.
</dd>
<dt>HWLOC_GROUPING=1</dt>
<dd>enables or disables objects grouping based on distances.
By default, hwloc uses distance matrices between objects (either read
from the OS or given by the user) to find groups of close objects.
These groups are described by adding intermediate Group objects in the topology.
Setting this environment variable to 1 will disable this grouping.
Setting this environment variable to 0 will disable this grouping.
This variable supersedes the obsolete HWLOC_IGNORE_DISTANCES variable.
</dd>
<dt>HWLOC_GROUPING_ACCURACY=0.05</dt>
<dd>relaxes distance comparison during grouping.
By default, objects may be grouped if their distances form a minimal
distance graph. When setting this variable to 0.02, these distances
do not have to be strictly equal anymore, they may just be equal
with a 2% error.
If set to <tt>try</tt> instead of a numerical value, hwloc will try
to group with perfect accuracy (0, the default), then with 0.01, 0.02,
0.05 and finally 0.1.</dd>
<dt>HWLOC_GROUPING_VERBOSE=0</dt>
<dd>enables or disables some verbose messages during grouping.
If this variable is set to 1, some debug messages will be displayed
during distance-based grouping of objects even if debug was not specific
at configure time.
This is useful when trying to find an interesting distance grouping
accuracy.</dd>
<dt>HWLOC_&lt;type&gt;_DISTANCES=index,...:X*Y</dt>
<dt>HWLOC_&lt;type&gt;_DISTANCES=index,...:X*Y*Z</dt>
<dt>HWLOC_&lt;type&gt;_DISTANCES=index,...:distance,...</dt>
<dd>sets a distance matrix for objects of the given type and physical indexes.
The type should be given as its case-sensitive stringified value
(e.g. <tt>NUMANode</tt>, <tt>Socket</tt>, <tt>Cache</tt>, <tt>Core</tt>, <tt>PU</tt>).
The variable value starts with a comma-separated list of the objects'
If another distance matrix already exists for the given type,