doc: Enable doxygen on hwloc/diff.h and add som...

doc: Enable doxygen on hwloc/diff.h and add some specific paragraphs about it

This commit was SVN r5806.

diff --git a/README b/README
index 04951dfea2cf252f609f2b7854d91546306ded4c..7f8acb91f4d841c6c2ccb532b9e650aa0f8e88c3 100644 (file)
--- a/README
+++ b/README
@@ -719,5 +719,5 @@ Make sure to have had a look at those too!
 
 -------------------------------------------------------------------------------
 
-Generated on Tue Sep 10 2013 15:47:42 for Hardware Locality (hwloc) by   
+Generated on Tue Sep 10 2013 16:08:12 for Hardware Locality (hwloc) by   
 doxygen 1.8.4

diff --git a/doc/Makefile.am b/doc/Makefile.am
index b622263fe952aca852b48814c90513bbd720542b..ed49cf0b425c8f465777eedc0acc8581e007edff 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -66,6 +66,7 @@ dox_inputs = $(DOX_CONFIG) \
        $(HWLOC_top_srcdir)/include/hwloc.h \
        $(HWLOC_top_srcdir)/include/hwloc/helper.h \
        $(HWLOC_top_srcdir)/include/hwloc/bitmap.h \
+       $(HWLOC_top_srcdir)/include/hwloc/diff.h \
        $(HWLOC_top_srcdir)/include/hwloc/plugins.h \
        $(HWLOC_top_srcdir)/include/hwloc/glibc-sched.h \
        $(HWLOC_top_srcdir)/include/hwloc/linux.h \
@@ -613,6 +614,28 @@ man3_helper_advanced_io_DATA = \
         $(DOX_MAN_DIR)/man3/hwloc_bridge_covers_pcibus.3 \
         $(DOX_MAN_DIR)/man3/hwloc_get_hostbridge_by_pcibus.3
 
+man3_diffdir = $(man3dir)
+man3_diff_DATA = \
+        $(DOX_MAN_DIR)/man3/hwlocality_diff.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_obj_attr_type_e.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_obj_attr_u.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_type_e.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_OBJ_ATTR.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_u.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_build.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_apply_flags_e.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_apply.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_destroy.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_load_xml.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_export_xml.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_load_xmlbuffer.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_topology_diff_export_xmlbuffer.3
+
 man3_cudadir = $(man3dir)
 man3_cuda_DATA = \
         $(DOX_MAN_DIR)/man3/hwlocality_opencl.3 \

diff --git a/doc/doxygen-config.cfg.in b/doc/doxygen-config.cfg.in
index c36b454b090d53e4872c45c104b6a39b90443ea4..e8ac777e2407c2981a64c9037c880e8f958c56fe 100644 (file)
--- a/doc/doxygen-config.cfg.in
+++ b/doc/doxygen-config.cfg.in
@@ -11,6 +11,7 @@ INPUT          = \
                @top_srcdir@/include/hwloc.h \
                @top_srcdir@/include/hwloc/helper.h \
                @top_srcdir@/include/hwloc/bitmap.h \
+               @top_srcdir@/include/hwloc/diff.h \
                @top_srcdir@/include/hwloc/plugins.h \
                @top_srcdir@/include/hwloc/linux.h \
                @top_srcdir@/include/hwloc/linux-libnuma.h \

diff --git a/doc/hwloc.doxy b/doc/hwloc.doxy
index f5f60dd18b5f26c585fc50f513e196feb6dfaa02..a6e36ba0a856f4fd1ff495328ea5f7c571d1828c 100644 (file)
--- a/doc/hwloc.doxy
+++ b/doc/hwloc.doxy
@@ -896,6 +896,13 @@ information (see \ref attributes_info for details).
 It reads an input topology from a XML file and outputs
 the annotated topology as another XML file.
 
+\section cli_hwloc_diffpatch hwloc-diff and hwloc-patch
+
+hwloc-diff computes the difference between two topologies
+and outputs it to another XML file.
+hwloc-patch reads such a difference file and applies to
+another topology.
+
 \section cli_hwloc_assembler hwloc-assembler
 
 hwloc-assembler combines several XML topology files into a single
@@ -1712,6 +1719,8 @@ This behavior may be reverted by asserting that loaded file really
 matches the underlying system with the HWLOC_THISSYSTEM environment
 variable or the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.
 
+\note hwloc also offers the ability to export/import \ref hwlocality_diff.
+
 \note XML topology files are not localized. They use a dot as a
 decimal separator. Therefore any exported topology can be
 reloaded on any other machine without requiring to change the
@@ -2532,6 +2541,20 @@ interface, and the import/export may also be directed to memory buffer
 See also \ref xml.
 
 
+\section faq_diff How to avoid memory waste when manipulating multiple similar topologies?
+
+hwloc does not share information between topologies.
+If multiple similar topologies are loaded in memory, for instance
+the topologies of different identical nodes of a cluster,
+lots of information will be duplicated.
+
+hwloc/diff.h (see also \ref hwlocality_diff) offers the ability to
+compute topology differences, apply or unapply them, or export/import
+to/from XML.
+However this feature is limited to basic differences such as attribute changes.
+It does not support complex modifications such as adding or removing some objects.
+
+
 \section faq_slow_lstopo Why is lstopo slow?
 
 lstopo enables most hwloc discovery flags by default so that the output