Open MPI logo

Hardware Locality Development Mailing List Archives

  |   Home   |   Support   |   FAQ   |   all Hardware Locality Development mailing list

Subject: [hwloc-devel] Fwd: [hwloc-svn] svn:hwloc r1261
From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2009-10-29 13:57:23


Can you guys eyeball the docs changes I made before I move them over
to the release branch?

I think all the changes should be paletable, but just wanted to be
sure...

Begin forwarded message:

> From: <jsquyres_at_[hidden]>
> Date: October 29, 2009 1:55:17 PM EDT
> To: <hwloc-svn_at_[hidden]>
> Subject: [hwloc-svn] svn:hwloc r1261
> Reply-To: <hwloc-devel_at_[hidden]>
>
> Author: jsquyres
> Date: 2009-10-29 13:55:16 EDT (Thu, 29 Oct 2009)
> New Revision: 1261
> URL: https://svn.open-mpi.org/trac/hwloc/changeset/1261
>
> Log:
> Updates to frontmatter of the doxy docs.
>
> Text files modified:
> trunk/doc/hwloc-hello.c | 8 +
> trunk/doc/hwloc.doxy | 180 +++++++++++++++++++++++
> +----------------
> 2 files changed, 115 insertions(+), 73 deletions(-)
>
> Modified: trunk/doc/hwloc-hello.c
> =
> =
> =
> =
> =
> =
> =
> =
> ======================================================================
> --- trunk/doc/hwloc-hello.c (original)
> +++ trunk/doc/hwloc-hello.c 2009-10-29 13:55:16 EDT (Thu, 29 Oct
> 2009)
> @@ -1,4 +1,10 @@
> -/* topo-hello.c */
> +/* Example hwloc API program.
> + *
> + * Copyright © 2009 INRIA, Université Bordeaux 1
> + *
> + * topo-hello.c
> + */
> +
> #include <hwloc.h>
>
> static void print_children(hwloc_topology_t topology, hwloc_obj_t
> obj, int depth)
>
> Modified: trunk/doc/hwloc.doxy
> =
> =
> =
> =
> =
> =
> =
> =
> ======================================================================
> --- trunk/doc/hwloc.doxy (original)
> +++ trunk/doc/hwloc.doxy 2009-10-29 13:55:16 EDT (Thu, 29 Oct
> 2009)
> @@ -15,83 +15,111 @@
> \endhtmlonly
> \section Introduction
>
> -hwloc provides a portable abstraction (across OS, versions,
> architectures,
> -...) of the hierarchical topology of modern architectures. It
> primarily aims at
> -helping high-performance computing applications with gathering
> information about
> -the hardware so as to exploit it accordingly and efficiently.
> -
> -hwloc provides a hierarchical view of the machine, NUMA memory nodes,
> -sockets, shared caches, cores and simultaneous multithreading. It
> also gathers
> -various attributes such as cache and memory information.
> +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
> +processor "threads". 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 locality on modern computing platforms.
> +
> +*** Note that the hwloc project represents the merger of the
> +libtopology project from INRIA and the Portable Linux Processor
> +Affinity (PLPA) sub-project from Open MPI. *Both of these prior
> +projects are now deprecated.* The first hwloc release is
> essentially a
> +"re-branding" of the libtopology code base, but with both a few
> +genuinely new features and a few PLPA-like features added in. More
> +new features and more PLPA-like features will be added to hwloc over
> +time.
>
> hwloc supports the following operating systems:
>
> <ul>
> - <li> Linux (including old kernels not having sysfs topology
> information, with
> - knowledge of cpusets, offline cpus, and Kerrighed support)
> - <li> Solaris
> - <li> AIX
> - <li> Darwin
> - <li> OSF/1 (aka. Tru64)
> - <li> HP-UX
> - <li> Windows
> - <li> For other OSes, only the number of processors is available
> for now.
> +<li>Linux (including old kernels not having sysfs topology
> +information, with knowledge of cpusets, offline cpus, and Kerrighed
> +support)</li>
> +<li>Solaris</li>
> +<li>AIX</li>
> +<li>Darwin / OS X</li>
> +<li>OSF/1 (a.k.a., Tru64)</li>
> +<li>HP-UX</li>
> +<li>Microsoft Windows</li>
> </ul>
>
> +hwloc only reports the number of processors on unsupported operating
> +systems; no topology information is available.
> +
> For development and debugging purposes, hwloc also offers the
> ability to
> -work on fake topologies:
> +work on "fake" topologies:
>
> <ul>
> - <li> Symmetrical tree of resources generated from a list of level
> arities
> - <li> Remote machine simulation through the gathering of Linux
> sysfs topology files
> + <li> Symmetrical tree of resources generated from a list of level
> arities</li>
> + <li> Remote machine simulation through the gathering of Linux
> sysfs topology files</li>
> </ul>
>
> -hwloc may also display the topology in a convenient format, either in
> -graphical mode, or by exporting in PDF, PNG, FIG, ... format, or in
> text mode
> -(see Examples below).
> +hwloc can display the topology in a human-readable format, either in
> +graphical mode (X11), or by exporting in one of several different
> +formats, including: plain text, PDF, PNG, and FIG (see Examples
> +below). Note that some of the export formats require additional
> +support libraries.
>
> hwloc offers a programming interface for manipulating topologies and
> -objects. It also brings a powerful cpu bitmap API that is used to
> describe
> -topology objects location on physical/logical processors. See the
> \ref interface
> -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, ...
> +objects. It also brings a powerful CPU bitmap API that is used to
> +describe topology objects location on physical/logical processors.
> See
> +the \ref interface 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.
>
> \htmlonly
> </div><div class="section" id="installation">
> \endhtmlonly
> \section installation Installation
>
> -hwloc (http://www.open-mpi.org/projects/hwloc/) is available under
> the BSD license.
> -It is hosted by Open MPI (http://www.open-mpi.org/).
> -The current SVN snapshot can be fetched with:
> -
> -<ul>
> - <li>svn checkout http://svn.open-mpi.org/svn/hwloc/trunk hwloc-trunk
> - <li>cd hwloc-trunk
> - <li>./autogen.sh
> -</ul>
> -
> -Note that autoconf >=2.60, automake >=1.10 and libtool >=2.2.6 are
> required in that case.
> -
> -Installation by itself is as usual:
> -
> -<ul>
> - <li>./configure --prefix=...
> - <li>make
> - <li>make install
> -</ul>
> -
> -Lstopo's fig support is always available. To get support for pdf,
> ps and png
> -support, cairo is needed. To get support for xml, libxml2 is needed.
> +hwloc (http://www.open-mpi.org/projects/hwloc/) is available under
> the
> +BSD license. It is hosted as a sub-project of the overall Open MPI
> +project (http://www.open-mpi.org/). Note that hwloc does not require
> +any functionality from Open MPI -- it is a wholly separate (and much
> +smaller!) project and code base. It just happens to be hosted as
> part
> +of the overall Open MPI project.
> +
> +Nightly development snapshots are available on the web site.
> +Additionally, the code can be directly checked out of Subversion:
> +
> +<pre>
> +shell$ svn checkout http://svn.open-mpi.org/svn/hwloc/trunk hwloc-
> trunk
> +shell$ cd hwloc-trunk
> +shell$ ./autogen.sh
> +</pre>
> +
> +Note that GNU Autoconf >=2.60, Automake >=1.10 and Libtool >=2.2.6
> are
> +required when building from a Subversion checkout.
> +
> +Installation by itself is the fairly common GNU-based process:
> +
> +<pre>
> +shell$ ./configure --prefix=...
> +shell$ make
> +shell$ make install
> +</pre>
> +
> +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.
>
> \htmlonly
> </div><div class="section" id="examples">
> \endhtmlonly
> \section examples Examples
>
> - On a 4-socket 2-core machine with hyperthreading, the \c lstopo
> tool may
> - show the following outputs:
> +On a 4-socket 2-core machine with hyperthreading, the \c lstopo tool
> +may show the following outputs:
>
> \image html dudley.png
> \image latex dudley.png width=\textwidth
> @@ -162,7 +190,8 @@
> L2(1024KB) + L1(64KB) + Core#1 + P#15
> \endcode
>
> - On a 2-socket quad-core Xeon (pre-Nehalem ones assembling 2 dual-
> core dies into each socket):
> + On a 2-socket quad-core Xeon (pre-Nehalem, with 2 dual-core dies
> into
> + each socket):
>
> \image html emmett.png
> \image latex emmett.png width=\textwidth
> @@ -191,20 +220,22 @@
>
> \section interface Programming interface
>
> -The basic interface is available in hwloc.h . It mostly offers low-
> level
> -routines for advanced programmers that want to manually manipulate
> objects
> -and follow links between them. Most users should look at hwloc/
> helper.h
> -which provides a lot of interesting higher-level traversal examples.
> -
> -Each object contains a cpuset which describes the list of processors
> -that it contains. These cpusets may be used for \ref
> hwlocality_binding.
> -hwloc offers an extensive cpuset manipulation interface in hwloc/
> cpuset.h .
> +The basic interface is available in hwloc.h. It mostly offers
> +low-level routines for advanced programmers that want to manually
> +manipulate objects and follow links between them. Developers should
> +look at hwloc/helper.h, which provides good higher-level topology
> +traversal examples.
> +
> +Each object contains a cpuset describing the list of processors that
> +it contains. These cpusets may be used for \ref hwlocality_binding.
> +hwloc offers an extensive cpuset manipulation interface in
> +hwloc/cpuset.h.
>
> Moreover, hwloc also comes with additional helpers for
> interoperability with several commonly used environments. For Linux,
> -some specific helpers are available in hwloc/linux.h , and
> +some specific helpers are available in hwloc/linux.h, and
> hwloc/linux-libnuma.h if using libnuma. On glibc-based systems,
> -additional helpers are available in hwloc/glibc-sched.h . For Linux
> +additional helpers are available in hwloc/glibc-sched.h. For Linux
> systems with the OpenFabrics verbs library, some dedicated helpers
> are
> provided in hwloc/openfabrics-verbs.h (this helper file is not yet
> useful on non-Linux systems with the OpenFabrics verbs library).
> @@ -212,10 +243,14 @@
> To precisely define the vocabulary used by hwloc, a \ref glossary is
> available and should probably be read first.
>
> -Further documentation is available in html, manual pages, and pdf
> format
> -in the source tarball in doc/doxygen-doc/ (after doxygen compilation
> -for svn checkouts) and are installed in $prefix/share/doc/hwloc/ and
> -the usual manual repository.
> +Further documentation is available in a full set of HTML pages, man
> +pages, and self-contained PDF files (formatted for both both US
> letter
> +and A4 formats) in the source tarball in doc/doxygen-doc/. If you
> are
> +building from a Subversion checkout, you will need to have Doxygen
> and
> +pdflatex installed -- the documentation will be built during the
> +normal "make" process. The documentation is installed during "make
> +install" to $prefix/share/doc/hwloc/ and your systems default man
> page
> +tree (under $prefix, of course).
>
> The following section presents an example of API usage.
>
> @@ -225,11 +260,12 @@
> that just prints the topology and binds itself to the first
> processor of the
> second core of the machine.
>
> -Hardware Location provides a pkg-config object, so compiling the
> example boils down to
> +Hardware Location provides a pkg-config object, so compiling the
> +example boils down to
>
> \verbatim
> -CFLAGS+=$(pkg-config --cflags hwloc)
> -LDLIBS+=$(pkg-config --libs hwloc)
> +CFLAGS += $(pkg-config --cflags hwloc)
> +LDLIBS += $(pkg-config --libs hwloc)
> cc hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
> \endverbatim
>
> @@ -259,7 +295,7 @@
>
> libtopology was initially developed by the INRIA Runtime Team-Project
> (http://runtime.bordeaux.inria.fr/) (headed by Raymond Namyst
> -(http://dept-info.labri.fr/~namyst/)). PLPA was initially developed
> by
> +(http://dept-info.labri.fr/~namyst/). PLPA was initially developed by
> the Open MPI development team as a sub-project. Both are now
> deprecated
> in favor of hwloc, which is distributed as an Open MPI sub-project.
>
> @@ -328,7 +364,7 @@
> \image html diagram.png
> \image latex diagram.eps width=\textwidth
>
> -It can be noticed that for Processor objects, the logical index,
> computed
> +It should be noted that for Processor objects, the logical index,
> computed
> linearly by hwloc, is not the same as the OS index.
>
> */
> _______________________________________________
> hwloc-svn mailing list
> hwloc-svn_at_[hidden]
> http://www.open-mpi.org/mailman/listinfo.cgi/hwloc-svn
>

-- 
Jeff Squyres
jsquyres_at_[hidden]