[svn-r15957] Revised the help page of h5perf.

Tested on kagiso.

1 files changed, 49 insertions, 27 deletions

diff --git a/perform/pio_perf.c b/perform/pio_perf.c
index 2275646..b19c7fb 100644
--- a/perform/pio_perf.c
+++ b/perform/pio_perf.c
@@ -1582,20 +1582,24 @@ usage(const char *prog)
 #endif  /* 0 */
         printf("     -B S, --block-size=S        Block size within transfer buffer\n");
         printf("                                 (see below for description)\n");
-        printf("                                 [default: half the number of bytes per processor per dataset]\n");
-        printf("     -c, --chunk                 Create HDF5 datasets chunked [default: off]\n");
+        printf("                                 [default: half the number of bytes per process\n");
+        printf("                                           per dataset]\n");
+        printf("     -c, --chunk                 Create HDF5 datasets using chunked storage\n");
+        printf("                                 [default: contiguous storage]\n");
         printf("     -C, --collective            Use collective I/O for MPI and HDF5 APIs\n");
-        printf("                                 [default: off (i.e. independent I/O)]\n");
-        printf("     -d N, --num-dsets=N         Number of datasets per file [default:1]\n");
+        printf("                                 [default: independent I/O)\n");
+        printf("     -d N, --num-dsets=N         Number of datasets per file [default: 1]\n");
         printf("     -D DL, --debug=DL           Indicate the debugging level\n");
         printf("                                 [default: no debugging]\n");
         printf("     -e S, --num-bytes=S         Number of bytes per process per dataset\n");
+        printf("                                 (see below for description)\n");
         printf("                                 [default: 256K for 1D, 8K for 2D]\n");
         printf("     -F N, --num-files=N         Number of files [default: 1]\n");
-        printf("     -g, --geometry              Use 2D geometry [default: 1D]\n");
+        printf("     -g, --geometry              Use 2D geometry [default: 1D geometry]\n");
         printf("     -i N, --num-iterations=N    Number of iterations to perform [default: 1]\n");
-        printf("     -I, --interleaved           Interleaved block I/O (see below for example)\n");
-        printf("                                 [default: Contiguous block I/O]\n");
+        printf("     -I, --interleaved           Interleaved access pattern\n");
+        printf("                                 (see below for example)\n");
+        printf("                                 [default: Contiguous access pattern]\n");
         printf("     -m, --mpi-posix             Use MPI-posix driver for HDF5 I/O\n");
         printf("                                 [default: use MPI-I/O driver]\n");
         printf("     -o F, --output=F            Output raw data into file F [default: none]\n");
@@ -1606,9 +1610,12 @@ usage(const char *prog)
         printf("                                 [default: 1]\n");
         printf("     -w, --write-only            Perform write tests not the read tests\n");
         printf("     -x S, --min-xfer-size=S     Minimum transfer buffer size\n");
-        printf("                                 [default: half the number of bytes per processor per dataset]\n");
+        printf("                                 (see below for description)\n");
+        printf("                                 [default: half the number of bytes per process\n");
+        printf("                                           per dataset]\n");
         printf("     -X S, --max-xfer-size=S     Maximum transfer buffer size\n");
-        printf("                                 [default: the number of bytes per processor per dataset]\n");
+        printf("                                 [default: the number of bytes per process per\n");
+        printf("                                           dataset]\n");
         printf("\n");
         printf("  F  - is a filename.\n");
         printf("  N  - is an integer >=0.\n");
@@ -1626,19 +1633,25 @@ usage(const char *prog)
         printf("\n");
         printf("      Example: --api=mpiio,phdf5\n");
         printf("\n");
+        printf("  Dataset size:\n");
+        printf("      Depending on the selected geometry, each test dataset is either a linear\n");
+        printf("      array of size bytes-per-process * num-processes, or a square array of size\n");
+        printf("      (bytes-per-process * num-processes) x (bytes-per-process * num-processes).\n");
+        printf("\n");
         printf("  Block size vs. Transfer buffer size:\n");
-        printf("      The transfer buffer size is the size of a buffer in memory, which is\n");
-        printf("      broken into 'block size' pieces and written to the file.  The pattern\n");
-        printf("      of the blocks in the file is described below in the 'Interleaved vs.\n");
-        printf("      Contiguous blocks' example.\n");
+        printf("      buffer-size controls the size of the memory buffer, which is broken into\n");
+        printf("      blocks and written to the file. Depending on the selected geometry, each\n");
+        printf("      block can be a linear array of size block-size or a square array of size\n");
+        printf("      block-size x block-size. The arrangement in which blocks are written is\n");
+        printf("      determined by the access pattern.\n");
         printf("\n");
-        printf("      If the collective I/O option is given, the blocks in each transfer buffer\n");
-        printf("      are written at once with an MPI derived type, for the MPI-I/O and PHDF5\n");
-        printf("      APIs.\n");
+        printf("      In 1D geometry, the transfer buffer is a linear array of size buffer-size.\n");
+        printf("      In 2D geometry, it is a rectangular array of size block-size x buffer-size\n");
+        printf("      or buffer-size x block-size if interleaved pattern is selected.\n");
         printf("\n");
-        printf("  Interleaved vs. Contiguous blocks:\n");
-        printf("      When contiguous blocks are written to a dataset, the dataset is divided\n");
-        printf("      into '# processes' regions and each process writes data to its own region.\n");
+        printf("  Interleaved and Contiguous patterns in 1D geometry:\n");
+        printf("      When contiguous access pattern is chosen, the dataset is evenly divided\n");
+        printf("      into num-processes regions and each process writes data to its own region.\n");
         printf("      When interleaved blocks are written to a dataset, space for the first\n");
         printf("      block of the first process is allocated in the dataset, then space is\n");
         printf("      allocated for the first block of the second process, etc. until space is\n");
@@ -1646,14 +1659,23 @@ usage(const char *prog)
         printf("      the second block of the first process, the second block of the second\n");
         printf("      process, etc.\n");
         printf("\n");
-        printf("      For example, with a 4 process run, 1MB bytes-per-process, 256KB transfer\n");
-        printf("        buffer size, and 64KB block size,\n");
-        printf("          16 contiguous blocks per process are written to the file like so:\n");
-        printf("              1111111111111111222222222222222233333333333333334444444444444444\n");
-        printf("          16 interleaved blocks per process are written to the file like so:\n");
-        printf("              1234123412341234123412341234123412341234123412341234123412341234\n");
-        printf("        If collective I/O is turned on, all of the four blocks per transfer\n");
-        printf("        buffer will be written in one collective I/O call.\n");
+        printf("      For example, with a 3 process run, 512KB bytes-per-process, 256KB transfer\n");
+        printf("        buffer size, and 64KB block size, each process must issue 2 transfer\n");
+        printf("        requests to complete access to the dataset.\n");
+        printf("          Contiguous blocks of the first transfer request are written like so:\n");
+        printf("              1111----2222----3333----\n");
+        printf("          Interleaved blocks of the first transfer request are written like so:\n");
+        printf("              123123123123------------\n");
+        printf("        The actual number of I/O operations involved in a transfer request\n");
+        printf("        depends on the access pattern and communication mode.\n");
+        printf("        When using independent I/O with interleaved pattern, each process\n");
+        printf("        performs 4 small non-contiguous I/O operations per transfer request.\n");
+        printf("        If collective I/O is turned on, the combined content of the buffers of\n");
+        printf("        the 3 processes will be written using one collective I/O operation\n");
+        printf("        per transfer request.\n");
+        printf("\n");
+        printf("      For information about access patterns in 2D geometry, please refer to the\n");
+        printf("      HDF5 Reference Manual.\n");
         printf("\n");
         printf("  DL - is a list of debugging flags. Valid values are:\n");
         printf("          1 - Minimal\n");