Merge branch 'develop' into feature/coding_standardsfeature/coding_standards

1 files changed, 343 insertions, 324 deletions

diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h
index 514d1bf..221f569 100644
--- a/src/H5FDpublic.h
+++ b/src/H5FDpublic.h
@@ -6,389 +6,408 @@
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the COPYING file, which can be found at the root of the source code       *
- * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
  * If you do not have access to either file, you may request a copy from     *
  * help@hdfgroup.org.                                                        *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*
- * Programmer:  Robb Matzke <matzke@llnl.gov>
+ * Programmer:  Robb Matzke
  *              Monday, July 26, 1999
  */
-#ifndef _H5FDpublic_H
-#define _H5FDpublic_H
+#ifndef H5FDpublic_H
+#define H5FDpublic_H
 
-#include "H5public.h"
-#include "H5Fpublic.h"		/*for H5F_close_degree_t */
+/* Public headers needed by this file */
+#include "H5public.h"  /* Generic Functions */
+#include "H5Fpublic.h" /* Files */
 
-#define H5_HAVE_VFL 1 /*define a convenient app feature test*/
-#define H5FD_VFD_DEFAULT 0   /* Default VFL driver value */
+/*****************/
+/* Public Macros */
+/*****************/
 
-/* Types of allocation requests: see H5Fpublic.h  */
-typedef enum H5F_mem_t	H5FD_mem_t;
+#define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */
 
-/* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
- *
- * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they
- * are similar to fractal heap header blocks.
- *
- * Map "fractal heap" direct blocks to 'lheap' type file memory, since they
- * will be replacing local heaps.
- *
- * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they
- * represent large objects that are directly stored in the file.
- *
- *      -QAK
+/* VFD identifier values
+ * These are H5FD_class_value_t values, NOT hid_t values!
  */
-#define H5FD_MEM_FHEAP_HDR      H5FD_MEM_OHDR
-#define H5FD_MEM_FHEAP_IBLOCK   H5FD_MEM_OHDR
-#define H5FD_MEM_FHEAP_DBLOCK   H5FD_MEM_LHEAP
-#define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
+#define H5_VFD_INVALID  ((H5FD_class_value_t)(-1))
+#define H5_VFD_SEC2     ((H5FD_class_value_t)(0))
+#define H5_VFD_CORE     ((H5FD_class_value_t)(1))
+#define H5_VFD_LOG      ((H5FD_class_value_t)(2))
+#define H5_VFD_FAMILY   ((H5FD_class_value_t)(3))
+#define H5_VFD_MULTI    ((H5FD_class_value_t)(4))
+#define H5_VFD_STDIO    ((H5FD_class_value_t)(5))
+#define H5_VFD_SPLITTER ((H5FD_class_value_t)(6))
+#ifdef H5_HAVE_PARALLEL
+#define H5_VFD_MPIO ((H5FD_class_value_t)(7))
+#endif
+#ifdef H5_HAVE_DIRECT
+#define H5_VFD_DIRECT ((H5FD_class_value_t)(8))
+#endif
+#ifdef H5_HAVE_MIRROR_VFD
+#define H5_VFD_MIRROR ((H5FD_class_value_t)(9))
+#endif
+#ifdef H5_HAVE_LIBHDFS
+#define H5_VFD_HDFS ((H5FD_class_value_t)(10))
+#endif
+#ifdef H5_HAVE_ROS3_VFD
+#define H5_VFD_ROS3 ((H5FD_class_value_t)(11))
+#endif
 
-/* Map "free space" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
- *
- * Map "free space" serialized sections to 'lheap' type file memory, since they
- * are similar enough to local heap info.
+/* VFD IDs below this value are reserved for library use. */
+#define H5_VFD_RESERVED 256
+
+/* Maximum VFD ID */
+#define H5_VFD_MAX 65535
+
+/* Define VFL driver features that can be enabled on a per-driver basis */
+/* These are returned with the 'query' function pointer in H5FD_class_t */
+/*
+ * Defining H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that
+ * the library will attempt to allocate a larger block for metadata and
+ * then sub-allocate each metadata request from that larger block.
+ */
+#define H5FD_FEAT_AGGREGATE_METADATA 0x00000001
+/*
+ * Defining H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that
+ * the library will attempt to cache metadata as it is written to the file
+ * and build up a larger block of metadata to eventually pass to the VFL
+ * 'write' routine.
  *
- *      -QAK
+ * Distinguish between updating the metadata accumulator on writes and
+ * reads.  This is particularly (perhaps only, even) important for MPI-I/O
+ * where we guarantee that writes are collective, but reads may not be.
+ * If we were to allow the metadata accumulator to be written during a
+ * read operation, the application would hang.
+ */
+#define H5FD_FEAT_ACCUMULATE_METADATA_WRITE 0x00000002
+#define H5FD_FEAT_ACCUMULATE_METADATA_READ  0x00000004
+#define H5FD_FEAT_ACCUMULATE_METADATA                                                                        \
+    (H5FD_FEAT_ACCUMULATE_METADATA_WRITE | H5FD_FEAT_ACCUMULATE_METADATA_READ)
+/*
+ * Defining H5FD_FEAT_DATA_SIEVE for a VFL driver means that
+ * the library will attempt to cache raw data as it is read from/written to
+ * a file in a "data seive" buffer.  See Rajeev Thakur's papers:
+ *  http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz
+ *  http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz
+ */
+#define H5FD_FEAT_DATA_SIEVE 0x00000008
+/*
+ * Defining H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that
+ * the library will attempt to allocate a larger block for "small" raw data
+ * and then sub-allocate "small" raw data requests from that larger block.
+ */
+#define H5FD_FEAT_AGGREGATE_SMALLDATA 0x00000010
+/*
+ * Defining H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that
+ * the library will ignore the driver info that is encoded in the file
+ * for the VFL driver.  (This will cause the driver info to be eliminated
+ * from the file when it is flushed/closed, if the file is opened R/W).
+ */
+#define H5FD_FEAT_IGNORE_DRVRINFO 0x00000020
+/*
+ * Defining the H5FD_FEAT_DIRTY_DRVRINFO_LOAD for a VFL driver means that
+ * the library will mark the driver info dirty when the file is opened
+ * R/W.  This will cause the driver info to be re-encoded when the file
+ * is flushed/closed.
  */
-#define H5FD_MEM_FSPACE_HDR     H5FD_MEM_OHDR
-#define H5FD_MEM_FSPACE_SINFO   H5FD_MEM_LHEAP
+#define H5FD_FEAT_DIRTY_DRVRINFO_LOAD 0x00000040
+/*
+ * Defining H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that
+ * the handle for the VFD (returned with the 'get_handle' callback) is
+ * of type 'int' and is compatible with POSIX I/O calls.
+ */
+#define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080
+/*
+ * Defining H5FD_FEAT_HAS_MPI for a VFL driver means that
+ * the driver makes use of MPI communication and code may retrieve
+ * communicator/rank information from it
+ */
+#define H5FD_FEAT_HAS_MPI 0x00000100
+/*
+ * Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force
+ * the library to use the H5D_ALLOC_TIME_EARLY on dataset create
+ * instead of the default H5D_ALLOC_TIME_LATE
+ */
+#define H5FD_FEAT_ALLOCATE_EARLY 0x00000200
+/*
+ * Defining H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that
+ * the driver is able to use a file image in the fapl as the initial
+ * contents of a file.
+ */
+#define H5FD_FEAT_ALLOW_FILE_IMAGE 0x00000400
+/*
+ * Defining H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS for a VFL driver
+ * means that the driver is able to use callbacks to make a copy of the
+ * image to store in memory.
+ */
+#define H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS 0x00000800
+/*
+ * Defining H5FD_FEAT_SUPPORTS_SWMR_IO for a VFL driver means that the
+ * driver supports the single-writer/multiple-readers I/O pattern.
+ */
+#define H5FD_FEAT_SUPPORTS_SWMR_IO 0x00001000
+/*
+ * Defining H5FD_FEAT_USE_ALLOC_SIZE for a VFL driver
+ * means that the library will just pass the allocation size to the
+ * the driver's allocation callback which will eventually handle alignment.
+ * This is specifically used for the multi/split driver.
+ */
+#define H5FD_FEAT_USE_ALLOC_SIZE 0x00002000
+/*
+ * Defining H5FD_FEAT_PAGED_AGGR for a VFL driver
+ * means that the driver needs special file space mapping for paged aggregation.
+ * This is specifically used for the multi/split driver.
+ */
+#define H5FD_FEAT_PAGED_AGGR 0x00004000
+/*
+ * Defining H5FD_FEAT_DEFAULT_VFD_COMPATIBLE for a VFL driver
+ * that creates a file which is compatible with the default VFD.
+ * Generally, this means that the VFD creates a single file that follows
+ * the canonical HDF5 file format.
+ * Regarding the Splitter VFD specifically, only drivers with this flag
+ * enabled may be used as the Write-Only (W/O) channel driver.
+ */
+#define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE 0x00008000
+/*
+ * Defining H5FD_FEAT_MEMMANAGE for a VFL driver means that
+ * the driver uses special memory management routines or wishes
+ * to do memory management in a specific manner. Therefore, HDF5
+ * should request that the driver handle any memory management
+ * operations when appropriate.
+ */
+#define H5FD_FEAT_MEMMANAGE 0x00010000
+
+/* ctl function definitions: */
+#define H5FD_CTL_OPC_RESERVED 512 /* Opcodes below this value are reserved for library use */
+#define H5FD_CTL_OPC_EXPER_MIN                                                                               \
+    H5FD_CTL_OPC_RESERVED /* Minimum opcode value available for experimental use                             \
+                           */
+#define H5FD_CTL_OPC_EXPER_MAX                                                                               \
+    (H5FD_CTL_OPC_RESERVED + 511) /* Maximum opcode value available for experimental use */
 
-/* Map "shared object header message" master table to 'ohdr' type file memory,
- * since its a fair amount of work to add a new kind of file memory and they are
- * similar enough to object headers and probably too minor to deserve their own
- * type.
+/* ctl function op codes: */
+#define H5FD_CTL__INVALID_OPCODE              0
+#define H5FD_CTL__TEST_OPCODE                 1
+#define H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE 2
+#define H5FD_CTL__GET_MPI_RANK_OPCODE         3
+#define H5FD_CTL__GET_MPI_SIZE_OPCODE         4
+#define H5FD_CTL__MEM_ALLOC                   5
+#define H5FD_CTL__MEM_FREE                    6
+#define H5FD_CTL__MEM_COPY                    7
+
+/* ctl function flags: */
+
+/* Definitions:
  *
- * Map "shared object header message" indices to 'btree' type file memory,
- * since they are similar enough to B-tree nodes.
+ * WARNING: While the following definitions of Terminal
+ * and Passthrough VFDs should be workable for now, they
+ * have to be adjusted as our use cases for VFDs expand.
+ *
+ *                                   JRM -- 8/4/21
  *
- *      -QAK
- */
-#define H5FD_MEM_SOHM_TABLE     H5FD_MEM_OHDR
-#define H5FD_MEM_SOHM_INDEX     H5FD_MEM_BTREE
-
-/* Map "extensible array" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
  *
- * Map "extensible array" index blocks to 'ohdr' type file memory, since they
- * are similar to extensible array header blocks.
+ * Terminal VFD: Lowest VFD in the VFD stack through
+ * which all VFD calls pass.  Note that this definition
+ * is situational.  For example, the sec2 VFD is typically
+ * terminal.  However, in the context of the family file
+ * driver, it is not -- the family file driver is the
+ * bottom VFD through which all VFD calls pass, and thus
+ * it is terminal.
  *
- * Map "extensible array" super blocks to 'btree' type file memory, since they
- * are similar enough to B-tree nodes.
+ * Similarly, on the splitter VFD, a sec2 VFD on the
+ * R/W channel is terminal, but a sec2 VFD on the W/O
+ * channel is not.
  *
- * Map "extensible array" data blocks & pages to 'lheap' type file memory, since
- * they are similar enough to local heap info.
  *
- *      -QAK
+ * Pass through VFD:  Any VFD that relays all VFD calls
+ * (with the possible exception of some non-I/O related
+ * calls) to underlying VFD(s).
  */
-#define H5FD_MEM_EARRAY_HDR     H5FD_MEM_OHDR
-#define H5FD_MEM_EARRAY_IBLOCK  H5FD_MEM_OHDR
-#define H5FD_MEM_EARRAY_SBLOCK  H5FD_MEM_BTREE
-#define H5FD_MEM_EARRAY_DBLOCK  H5FD_MEM_LHEAP
-#define H5FD_MEM_EARRAY_DBLK_PAGE  H5FD_MEM_LHEAP
 
-/* Map "fixed array" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
+/* Unknown op codes should be ignored silently unless the
+ * H5FD_CTL__FAIL_IF_UNKNOWN_FLAG is set.
  *
- * Map "fixed array" data blocks & pages to 'lheap' type file memory, since
- * they are similar enough to local heap info.
+ * On terminal VFDs, unknown op codes should generate an
+ * error unconditionally if this flag is set.
  *
+ * On pass through VFDs, unknown op codes should be routed
+ * to the underlying VFD(s) as indicated by any routing
+ * flags.  In the absence of such flags, the VFD should
+ * generate an error.
  */
-#define H5FD_MEM_FARRAY_HDR     H5FD_MEM_OHDR
-#define H5FD_MEM_FARRAY_DBLOCK  H5FD_MEM_LHEAP
-#define H5FD_MEM_FARRAY_DBLK_PAGE  H5FD_MEM_LHEAP
+#define H5FD_CTL__FAIL_IF_UNKNOWN_FLAG 0x0001
 
-/*
- * A free-list map which maps all types of allocation requests to a single
- * free list.  This is useful for drivers that don't really care about
- * keeping different requests segregated in the underlying file and which
- * want to make most efficient reuse of freed memory.  The use of the
- * H5FD_MEM_SUPER free list is arbitrary.
+/* The H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG is used only
+ * by non-ternminal VFDs, and only applies to unknown
+ * opcodes. (known op codes should be handled as
+ * appropriate.)
+ *
+ * If this flag is set for an unknown op code, that
+ * op code should be passed to the next VFD down
+ * the VFD stack en-route to the terminal VFD.
+ * If that VFD does not support the ctl call, the
+ * pass through VFD should fail or succeed as directed
+ * by the  H5FD_CTL__FAIL_IF_UNKNOWN_FLAG.
  */
-#define H5FD_FLMAP_SINGLE {						      \
-    H5FD_MEM_SUPER,			/*default*/			      \
-    H5FD_MEM_SUPER,			/*super*/			      \
-    H5FD_MEM_SUPER,			/*btree*/			      \
-    H5FD_MEM_SUPER,			/*draw*/			      \
-    H5FD_MEM_SUPER,			/*gheap*/			      \
-    H5FD_MEM_SUPER,			/*lheap*/			      \
-    H5FD_MEM_SUPER			/*ohdr*/			      \
-}
+#define H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG 0x0002
 
-/*
- * A free-list map which segregates requests into `raw' or `meta' data
- * pools.
- */
-#define H5FD_FLMAP_DICHOTOMY {						      \
-    H5FD_MEM_SUPER,			/*default*/			      \
-    H5FD_MEM_SUPER,			/*super*/			      \
-    H5FD_MEM_SUPER,			/*btree*/			      \
-    H5FD_MEM_DRAW,			/*draw*/			      \
-    H5FD_MEM_DRAW,			/*gheap*/			      \
-    H5FD_MEM_SUPER,			/*lheap*/			      \
-    H5FD_MEM_SUPER			/*ohdr*/			      \
-}
+/*******************/
+/* Public Typedefs */
+/*******************/
 
 /*
- * The default free list map which causes each request type to use it's own
- * free-list.
+ * File driver identifiers.
+ *
+ * Values 0 through 255 are for drivers defined by the HDF5 library.
+ * Values 256 through 511 are available for testing new drivers.
+ * Subsequent values should be obtained from the HDF5 development
+ * team at mailto:help@hdfgroup.org.
  */
-#define H5FD_FLMAP_DEFAULT {						      \
-    H5FD_MEM_DEFAULT,			/*default*/			      \
-    H5FD_MEM_DEFAULT,			/*super*/			      \
-    H5FD_MEM_DEFAULT,			/*btree*/			      \
-    H5FD_MEM_DEFAULT,			/*draw*/			      \
-    H5FD_MEM_DEFAULT,			/*gheap*/			      \
-    H5FD_MEM_DEFAULT,			/*lheap*/			      \
-    H5FD_MEM_DEFAULT			/*ohdr*/			      \
-}
+typedef int H5FD_class_value_t;
 
+/* Types of allocation requests: see H5Fpublic.h  */
+typedef enum H5F_mem_t H5FD_mem_t;
 
-/* Define VFL driver features that can be enabled on a per-driver basis */
-/* These are returned with the 'query' function pointer in H5FD_class_t */
-    /*
-     * Defining H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that
-     * the library will attempt to allocate a larger block for metadata and
-     * then sub-allocate each metadata request from that larger block.
-     */
-#define H5FD_FEAT_AGGREGATE_METADATA    0x00000001
-    /*
-     * Defining H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that
-     * the library will attempt to cache metadata as it is written to the file
-     * and build up a larger block of metadata to eventually pass to the VFL
-     * 'write' routine.
-     *
-     * Distinguish between updating the metadata accumulator on writes and
-     * reads.  This is particularly (perhaps only, even) important for MPI-I/O
-     * where we guarantee that writes are collective, but reads may not be.
-     * If we were to allow the metadata accumulator to be written during a
-     * read operation, the application would hang.
-     */
-#define H5FD_FEAT_ACCUMULATE_METADATA_WRITE     0x00000002
-#define H5FD_FEAT_ACCUMULATE_METADATA_READ      0x00000004
-#define H5FD_FEAT_ACCUMULATE_METADATA   (H5FD_FEAT_ACCUMULATE_METADATA_WRITE|H5FD_FEAT_ACCUMULATE_METADATA_READ)
-    /*
-     * Defining H5FD_FEAT_DATA_SIEVE for a VFL driver means that
-     * the library will attempt to cache raw data as it is read from/written to
-     * a file in a "data seive" buffer.  See Rajeev Thakur's papers:
-     *  http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz
-     *  http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz
-     */
-#define H5FD_FEAT_DATA_SIEVE            0x00000008
-    /*
-     * Defining H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that
-     * the library will attempt to allocate a larger block for "small" raw data
-     * and then sub-allocate "small" raw data requests from that larger block.
-     */
-#define H5FD_FEAT_AGGREGATE_SMALLDATA   0x00000010
-    /*
-     * Defining H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that
-     * the library will ignore the driver info that is encoded in the file
-     * for the VFL driver.  (This will cause the driver info to be eliminated
-     * from the file when it is flushed/closed, if the file is opened R/W).
-     */
-#define H5FD_FEAT_IGNORE_DRVRINFO       0x00000020
-    /*
-     * Defining the H5FD_FEAT_DIRTY_DRVRINFO_LOAD for a VFL driver means that
-     * the library will mark the driver info dirty when the file is opened
-     * R/W.  This will cause the driver info to be re-encoded when the file
-     * is flushed/closed.
-     */
-#define H5FD_FEAT_DIRTY_DRVRINFO_LOAD   0x00000040
-    /*
-     * Defining H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that
-     * the handle for the VFD (returned with the 'get_handle' callback) is
-     * of type 'int' and is compatible with POSIX I/O calls.
-     */
-#define H5FD_FEAT_POSIX_COMPAT_HANDLE   0x00000080    
-    /*
-     * Defining H5FD_FEAT_HAS_MPI for a VFL driver means that
-     * the driver makes use of MPI communication and code may retrieve
-     * communicator/rank information from it
-     */
-#define H5FD_FEAT_HAS_MPI               0x00000100
-    /*
-     * Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force
-     * the library to use the H5D_ALLOC_TIME_EARLY on dataset create
-     * instead of the default H5D_ALLOC_TIME_LATE
-     */
-#define H5FD_FEAT_ALLOCATE_EARLY        0x00000200
-    /* 
-     * Defining H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that
-     * the driver is able to use a file image in the fapl as the initial
-     * contents of a file.
-     */
-#define H5FD_FEAT_ALLOW_FILE_IMAGE      0x00000400
-    /*
-     * Defining H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS for a VFL driver
-     * means that the driver is able to use callbacks to make a copy of the
-     * image to store in memory.
-     */
-#define H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS 0x00000800
-    /*
-     * Defining H5FD_FEAT_SUPPORTS_SWMR_IO for a VFL driver means that the
-     * driver supports the single-writer/multiple-readers I/O pattern.
-     */
-#define H5FD_FEAT_SUPPORTS_SWMR_IO      0x00001000
-    /*
-     * Defining H5FD_FEAT_USE_ALLOC_SIZE for a VFL driver
-     * means that the library will just pass the allocation size to the
-     * the driver's allocation callback which will eventually handle alignment.
-     * This is specifically used for the multi/split driver.
-     */
-#define H5FD_FEAT_USE_ALLOC_SIZE	0x00002000
-    /*
-     * Defining H5FD_FEAT_PAGED_AGGR for a VFL driver
-     * means that the driver needs special file space mapping for paged aggregation.
-     * This is specifically used for the multi/split driver.
-     */
-#define H5FD_FEAT_PAGED_AGGR		0x00004000
-    /*
-     * Defining H5FD_FEAT_DEFAULT_VFD_COMPATIBLE for a VFL driver
-     * that creates a file which is compatible with the default VFD.
-     * Generally, this means that the VFD creates a single file that follows
-     * the canonical HDF5 file format.
-     */
-#define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE        0x00008000
-
-
-/* Forward declaration */
-typedef struct H5FD_t H5FD_t;
-
-/* Class information for each file driver */
-typedef struct H5FD_class_t {
-    const char *name;
-    haddr_t maxaddr;
-    H5F_close_degree_t fc_degree;
-    herr_t  (*terminate)(void);
-    hsize_t (*sb_size)(H5FD_t *file);
-    herr_t  (*sb_encode)(H5FD_t *file, char *name/*out*/,
-                         unsigned char *p/*out*/);
-    herr_t  (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
-    size_t  fapl_size;
-    void *  (*fapl_get)(H5FD_t *file);
-    void *  (*fapl_copy)(const void *fapl);
-    herr_t  (*fapl_free)(void *fapl);
-    size_t  dxpl_size;
-    void *  (*dxpl_copy)(const void *dxpl);
-    herr_t  (*dxpl_free)(void *dxpl);
-    H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl,
-                    haddr_t maxaddr);
-    herr_t  (*close)(H5FD_t *file);
-    int     (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
-    herr_t  (*query)(const H5FD_t *f1, unsigned long *flags);
-    herr_t  (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
-    haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
-    herr_t  (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
-                    haddr_t addr, hsize_t size);
-    haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type);
-    herr_t  (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr);
-    haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type);
-    herr_t  (*get_handle)(H5FD_t *file, hid_t fapl, void**file_handle);
-    herr_t  (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl,
-                    haddr_t addr, size_t size, void *buffer);
-    herr_t  (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl,
-                     haddr_t addr, size_t size, const void *buffer);
-    herr_t  (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
-    herr_t  (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
-    herr_t  (*lock)(H5FD_t *file, hbool_t rw);
-    herr_t  (*unlock)(H5FD_t *file);
-    H5FD_mem_t fl_map[H5FD_MEM_NTYPES];
-} H5FD_class_t;
-
-/* A free list is a singly-linked list of address/size pairs. */
-typedef struct H5FD_free_t {
-    haddr_t		addr;
-    hsize_t		size;
-    struct H5FD_free_t	*next;
-} H5FD_free_t;
-
-/*
- * The main datatype for each driver. Public fields common to all drivers
- * are declared here and the driver appends private fields in memory.
+/**
+ * Define enum for the source of file image callbacks
  */
-struct H5FD_t {
-    hid_t               driver_id;      /*driver ID for this file   */
-    const H5FD_class_t *cls;            /*constant class info       */
-    unsigned long       fileno;         /* File 'serial' number     */
-    unsigned            access_flags;   /* File access flags (from create or open) */
-    unsigned long       feature_flags;  /* VFL Driver feature Flags */
-    haddr_t             maxaddr;        /* For this file, overrides class */
-    haddr_t             base_addr;      /* Base address for HDF5 data w/in file */
-
-    /* Space allocation management fields */
-    hsize_t             threshold;      /* Threshold for alignment  */
-    hsize_t             alignment;      /* Allocation alignment     */
-    hbool_t             paged_aggr;     /* Paged aggregation for file space is enabled or not */
-};
-
-/* Define enum for the source of file image callbacks */
+//! <!-- [H5FD_file_image_op_t_snip] -->
 typedef enum {
     H5FD_FILE_IMAGE_OP_NO_OP,
-    H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET,     
+    H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET,
+    /**< Passed to the \p image_malloc and \p image_memcpy callbacks when a
+     * file image buffer is to be copied while being set in a file access
+     * property list (FAPL)*/
     H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY,
+    /**< Passed to the \p image_malloc and \p image_memcpy callbacks
+     * when a file image buffer is to be copied when a FAPL is copied*/
     H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET,
+    /**<Passed to the \p image_malloc and \p image_memcpy callbacks when
+     * a file image buffer is to be copied while being retrieved from a FAPL*/
     H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE,
+    /**<Passed to the \p image_free callback when a file image
+     * buffer is to be released during a FAPL close operation*/
     H5FD_FILE_IMAGE_OP_FILE_OPEN,
+    /**<Passed to the \p image_malloc and
+     * \p image_memcpy callbackswhen a
+     * file image buffer is to be copied during a file open operation \n
+     * While the file image being opened will typically be copied from a
+     * FAPL, this need not always be the case. For example, the core file
+     * driver, also known as the memory file driver, takes its initial
+     * image from a file.*/
     H5FD_FILE_IMAGE_OP_FILE_RESIZE,
+    /**<Passed to the \p image_realloc callback when a file driver needs
+     * to resize an image buffer*/
     H5FD_FILE_IMAGE_OP_FILE_CLOSE
+    /**<Passed to the \p image_free callback when an image buffer is to
+     * be released during a file close operation*/
 } H5FD_file_image_op_t;
+//! <!-- [H5FD_file_image_op_t_snip] -->
 
-/* Define structure to hold file image callbacks */
+/**
+ * Define structure to hold file image callbacks
+ */
+//! <!-- [H5FD_file_image_callbacks_t_snip] -->
 typedef struct {
-    void   *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, 
-                            void *udata);
-    void   *(*image_memcpy)(void *dest, const void *src, size_t size,
-                            H5FD_file_image_op_t file_image_op, void *udata);
-    void   *(*image_realloc)(void *ptr, size_t size, 
-                            H5FD_file_image_op_t file_image_op, void *udata);
-    herr_t  (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, 
+    /**
+     * \param[in] size Size in bytes of the file image buffer to allocate
+     * \param[in] file_image_op A value from H5FD_file_image_op_t indicating
+     *                          the operation being performed on the file image
+     *                          when this callback is invoked
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [image_malloc_snip] -->
+    void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata);
+    //! <!-- [image_malloc_snip] -->
+    /**
+     * \param[in] dest Address of the destination buffer
+     * \param[in] src Address of the source buffer
+     * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating
+     *                          the operation being performed on the file image
+     *                          when this callback is invoked
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [image_memcpy_snip] -->
+    void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op,
                           void *udata);
-    void   *(*udata_copy)(void *udata);
-    herr_t  (*udata_free)(void *udata);
+    //! <!-- [image_memcpy_snip] -->
+    /**
+     * \param[in] ptr Pointer to the buffer being reallocated
+     * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating
+     *                          the operation being performed on the file image
+     *                          when this callback is invoked
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [image_realloc_snip] -->
+    void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata);
+    //! <!-- [image_realloc_snip] -->
+    /**
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [image_free_snip] -->
+    herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata);
+    //! <!-- [image_free_snip] -->
+    /**
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [udata_copy_snip] -->
+    void *(*udata_copy)(void *udata);
+    //! <!-- [udata_copy_snip] -->
+    /**
+     * \param[in] udata Value passed in in the H5Pset_file_image_callbacks
+     *            parameter \p udata
+     */
+    //! <!-- [udata_free_snip] -->
+    herr_t (*udata_free)(void *udata);
+    //! <!-- [udata_free_snip] -->
+    /**
+     * \brief The final field in the #H5FD_file_image_callbacks_t struct,
+     *        provides a pointer to user-defined data. This pointer will be
+     *        passed to the image_malloc, image_memcpy, image_realloc, and
+     *        image_free callbacks. Define udata as NULL if no user-defined
+     *        data is provided.
+     */
     void *udata;
 } H5FD_file_image_callbacks_t;
+//! <!-- [H5FD_file_image_callbacks_t_snip] -->
+
+/**
+ * Define structure to hold "ctl memory copy" parameters
+ */
+//! <!-- [H5FD_ctl_memcpy_args_t_snip] -->
+typedef struct H5FD_ctl_memcpy_args_t {
+    void *      dstbuf;  /**< Destination buffer */
+    hsize_t     dst_off; /**< Offset within destination buffer */
+    const void *srcbuf;  /**< Source buffer */
+    hsize_t     src_off; /**< Offset within source buffer */
+    size_t      len;     /**< Length of data to copy from source buffer */
+} H5FD_ctl_memcpy_args_t;
+//! <!-- [H5FD_ctl_memcpy_args_t_snip] -->
+
+/********************/
+/* Public Variables */
+/********************/
+
+/*********************/
+/* Public Prototypes */
+/*********************/
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /* Function prototypes */
-H5_DLL hid_t H5FDregister(const H5FD_class_t *cls);
-H5_DLL herr_t H5FDunregister(hid_t driver_id);
-H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id,
-                        haddr_t maxaddr);
-H5_DLL herr_t H5FDclose(H5FD_t *file);
-H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2);
-H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags);
-H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
-H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
-                       haddr_t addr, hsize_t size);
-H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type);
-H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa);
-H5_DLL haddr_t H5FDget_eof(H5FD_t *file, H5FD_mem_t type);
-H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void**file_handle);
-H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
-                       haddr_t addr, size_t size, void *buf/*out*/);
-H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id,
-                        haddr_t addr, size_t size, const void *buf);
-H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
-H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
-H5_DLL herr_t H5FDlock(H5FD_t *file, hbool_t rw);
-H5_DLL herr_t H5FDunlock(H5FD_t *file);
-
 /* Allows querying a VFD ID for features before the file is opened */
-H5_DLL herr_t H5FDdriver_query(hid_t driver_id, unsigned long *flags/*out*/);
+H5_DLL herr_t H5FDdriver_query(hid_t driver_id, unsigned long *flags /*out*/);
 
 #ifdef __cplusplus
 }
 #endif
 #endif
-