From ff3481d9577d0d826403bc03c4842f3bd5ed7c0d Mon Sep 17 00:00:00 2001 From: Christian Chilan Date: Sun, 26 Oct 2008 16:20:30 -0500 Subject: [svn-r15957] Revised the help page of h5perf. Tested on kagiso. --- perform/pio_perf.c | 76 +++++++++++++++++++++++++++++++++++------------------- 1 file 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"); -- cgit v0.12