cuphy_hdf5.h File Reference

Physical layer library support for HDF5 file I/O. More...

#include "cuphy.h"
#include "hdf5.h"
#include <stdlib.h>

Enumerations
enum	cuphyHDF5Status_t {   CUPHYHDF5_STATUS_SUCCESS = 0,   CUPHYHDF5_STATUS_INVALID_ARGUMENT = 1,   CUPHYHDF5_STATUS_INVALID_DATASET = 2,   CUPHYHDF5_STATUS_DATATYPE_ERROR = 3,   CUPHYHDF5_STATUS_DATASPACE_ERROR = 4,   CUPHYHDF5_STATUS_UNSUPPORTED_RANK = 5,   CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE = 6,   CUPHYHDF5_STATUS_INVALID_TENSOR_DESC = 7,   CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE = 8,   CUPHYHDF5_STATUS_TENSOR_MISMATCH = 9,   CUPHYHDF5_STATUS_UNKNOWN_ERROR = 10,   CUPHYHDF5_STATUS_ALLOC_FAILED = 11,   CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE = 12,   CUPHYHDF5_STATUS_READ_ERROR = 13,   CUPHYHDF5_STATUS_CONVERT_ERROR = 14,   CUPHYHDF5_STATUS_WRITE_ERROR = 15,   CUPHYHDF5_STATUS_DATASET_ERROR = 16,   CUPHYHDF5_STATUS_INVALID_NAME = 17,   CUPHYHDF5_STATUS_INCORRECT_OBJ_TYPE = 18,   CUPHYHDF5_STATUS_OBJ_CREATE_FAILURE = 19,   CUPHYHDF5_STATUS_VALUE_OUT_OF_RANGE = 20 }

Functions
cuphyHDF5Status_t	cuphyHDF5GetDatasetInfo (hid_t h5Dataset, int dimBufferSize, cuphyDataType_t *dataType, int *numDims, int dimensions[])
	Returns information about an HDF5 dataset. More...
const char *	cuphyHDF5GetErrorName (cuphyHDF5Status_t status)
	Returns a string version of an error code enumeration value. More...
const char *	cuphyHDF5GetErrorString (cuphyHDF5Status_t status)
	Returns the description string for an error code. More...
cuphyHDF5Status_t	cuphyHDF5GetStruct (hid_t h5Dataset, size_t numDim, const hsize_t *coord, cuphyHDF5Struct_t *s)
	Acquires a cuPHY HDF5 structure handle. More...
cuphyHDF5Status_t	cuphyHDF5GetStructScalar (cuphyVariant_t *res, const cuphyHDF5Struct_t s, const char *name, cuphyDataType_t valueAs)
	Retrieves a scalar value from a cuphy HDF5 struct. More...
cuphyHDF5Status_t	cuphyHDF5ReadDataset (const cuphyTensorDescriptor_t tensorDesc, void *addr, hid_t h5Dataset, cudaStream_t strm)
	Reads data from an HDF5 dataset into a cuPHY tensor. More...
cuphyHDF5Status_t	cuphyHDF5ReleaseStruct (cuphyHDF5Struct_t s)
	Releases a cuPHY HDF5 structure handle. More...
cuphyHDF5Status_t	cuphyHDF5WriteDataset (hid_t h5LocationID, const char *name, const cuphyTensorDescriptor_t tensorDesc, const void *addr, cudaStream_t strm)
	Writes data from a cuPHY tensor to an HDF5 dataset. More...
cuphyHDF5Status_t	cuphyHDF5WriteDatasetFromCPU (hid_t h5LocationID, const char *name, const cuphyDataType_t type, const int32_t size, void *pData)
	Writes data from CPU to an HDF5 dataset. More...

Detailed Description

Header file for the cuPHY HDF5 API

Enumeration Type Documentation

cuphyHDF5Status_t

enum cuphyHDF5Status_t

cuphyHDF5 error codes

Enumerator
CUPHYHDF5_STATUS_SUCCESS	The API call returned with no errors.
CUPHYHDF5_STATUS_INVALID_ARGUMENT	One or more of the arguments provided to the function was invalid.
CUPHYHDF5_STATUS_INVALID_DATASET	The HDF5 dataset argument provided was invalid.
CUPHYHDF5_STATUS_DATATYPE_ERROR	The HDF5 datatype is not supported by the cuPHY library.
CUPHYHDF5_STATUS_DATASPACE_ERROR	The HDF5 library returned an error creating or querying the dataspace.
CUPHYHDF5_STATUS_UNSUPPORTED_RANK	The HDF5 dataspace rank is not supported by cuPHY.
CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE	One or more HDF5 dataspace dimensions are larger than cuPHY supports.
CUPHYHDF5_STATUS_INVALID_TENSOR_DESC	An invalid tensor descriptor was provided.
CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE	The provided buffer size was inadequate.
CUPHYHDF5_STATUS_TENSOR_MISMATCH	Tensor descriptor arguments do not match in rank and/or dimension(s).
CUPHYHDF5_STATUS_UNKNOWN_ERROR	Unknown or unexpected internal error.
CUPHYHDF5_STATUS_ALLOC_FAILED	Memory allocation failed.
CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE	Creating or setting the cuPHY tensor descriptor failed.
CUPHYHDF5_STATUS_READ_ERROR	An HDF5 read error occurred.
CUPHYHDF5_STATUS_CONVERT_ERROR	A conversion error occurred, or an unsupported conversion was requested.
CUPHYHDF5_STATUS_WRITE_ERROR	An HDF5 write error occurred.
CUPHYHDF5_STATUS_DATASET_ERROR	An HDF5 dataset creation/query error occurred.
CUPHYHDF5_STATUS_INVALID_NAME	No such scalar or structure field with the given name exists.
CUPHYHDF5_STATUS_INCORRECT_OBJ_TYPE	The HDF5 object provided is not of the correct/expected type.
CUPHYHDF5_STATUS_OBJ_CREATE_FAILURE	HDF5 object creation failure.
CUPHYHDF5_STATUS_VALUE_OUT_OF_RANGE	Data conversion could not occur because an input value was out of range.

Function Documentation

cuphyHDF5GetDatasetInfo()

cuphyHDF5Status_t cuphyHDF5GetDatasetInfo	(	hid_t	h5Dataset,
		int	dimBufferSize,
		cuphyDataType_t *	dataType,
		int *	numDims,
		int	dimensions[]
	)

Determines the rank, dimensions, and datatype of an HDF5 dataset. The stored type of the dataset is mapped to the tensor element types supported by cuPHY.

Parameters

h5Dataset	- HDF5 dataset
dimBufferSize	- size of the array for the outputDimensions argument
dataType	- address for returned cuPHY datatype (may be NULL)
numDims	- address for returned rank (may be NULL)
dimensions	- array for storage of dataset dimensions (may be NULL if dimBufferSize is zero)

Returns CUPHYHDF5_STATUS_INVALID_DATASET if h5Dataset < 0.

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if dimBufferSize > 0 and outputDimensions is NULL.

Returns CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE if dimBufferSize is less than the HDF5 dataspace rank

Returns CUPHYHDF5_STATUS_DATATYPE_ERROR if the data type of the HDF5 dataset cannot be represented by a cuPHY tensor element type

Returns CUPHYHDF5_STATUS_DATASPACE_ERROR if the HDF5 dataspace cannot be queried

Returns CUPHYHDF5_STATUS_UNSUPPORTED_RANK if the HDF5 dataspace is larger than the maximum rank supported by the cuPHY library

Returns CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE if one or more of the HDF5 dataspace dimensions is larger than the maximum size supported by the cuPHY library

Returns CUPHYHDF5_STATUS_SUCCESS if the query was successful.

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_DATASET CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE CUPHYHDF5_STATUS_UNSUPPORTED_RANK CUPHYHDF5_STATUS_DATASPACE_ERROR CUPHYHDF5_STATUS_DATATYPE_ERROR CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString

cuphyHDF5GetErrorName()

const char* cuphyHDF5GetErrorName

(

cuphyHDF5Status_t

status

)

Returns a string version of an error code. If the error code is not recognized, "CUPHYHDF5_UNKNOWN_STATUS" is returned.

Parameters

status

- Status code for desired string

Returns

char* pointer to a NULL-terminated string

See also

cuphyHDF5GetErrorString, cuphyStatus_t

cuphyHDF5GetErrorString()

const char* cuphyHDF5GetErrorString

(

cuphyHDF5Status_t

status

)

Returns the description string for an error code. If the error code is not recognized, "Unknown status code" is returned.

Parameters

status

- Status code for desired string

Returns

char* pointer to a NULL-terminated string

See also

cuphyHDF5Status_t, cuphyHDF5GetErrorName

cuphyHDF5GetStruct()

cuphyHDF5Status_t cuphyHDF5GetStruct	(	hid_t	h5Dataset,
		size_t	numDim,
		const hsize_t *	coord,
		cuphyHDF5Struct_t *	s
	)

Creates a cuPHY HDF5 structure handle that references an instance of an HDF5 compound data type in the given HDF5 dataset. The numDim and coord arguments can be used to identify a specific instance when the dataset argument refers to an array of structures. For datasets with a single struct element, NULL can be specified for the coord argument (and the numDim value should be zero) to access the lone element. Otherwise, numDim should match the rank of the dataset, and one coordinate value for each dimension should be provided in the coord array. The (HDF5 library) reference count of the dataset is incremented so that the HDF5 dataset can be accessed during the lifetime of the cuphyHDF5Struct_t instance. The reference count will be decremented (and the object potentially destroyed) when the cuphyHDF5ReleaseStruct function is called.

Parameters

h5Dataset	- HDF5 dataset
numDim	- number of elements in the coord array (or zero)
coord	- array of indices for element to access (or NULL)
s	- address for returned cuphy HDF5 structure handle

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if h5Dataset < 0, or if s is NULL

Returns CUPHYHDF5_STATUS_INVALID_DATASET if the type of the HDF5 dataset is not the HDF5 compound datatype

Returns CUPHYHDF5_STATUS_DATASPACE_ERROR if an error occurs querying the dataspace of the given dataset

Returns CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE if the dataset rank is greater than 1 and numDim is zero (or coord is NULL), or if numDim is greater than 0 and coord is NULL

Returns CUPHYHDF5_STATUS_ALLOC_FAILED if memory for the internal data structure could not be allocated

Returns CUPHYHDF5_STATUS_INCORRECT_OBJ_TYPE if the given HDF5 id h5Dataset does not refer to a dataset

Returns CUPHYHDF5_STATUS_SUCCESS if the handle acquisition was successful

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_INVALID_DATASET CUPHYHDF5_STATUS_DATASPACE_ERROR CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE CUPHYHDF5_STATUS_ALLOC_FAILED;

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString,cuphyHDF5ReleaseStruct

cuphyHDF5GetStructScalar()

cuphyHDF5Status_t cuphyHDF5GetStructScalar	(	cuphyVariant_t *	res,
		const cuphyHDF5Struct_t	s,
		const char *	name,
		cuphyDataType_t	valueAs
	)

Retrieves a scalar value from a HDF5 compound dataset (structure), optionally converting the value to a caller provided type.

Parameters

res	- output value (variant)
s	- cuphy HDF5 structure handle
name	- name of field to retrieve
valueAs	- desired type of result (or CUPHY_VOID to use the stored type)

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if an of res, s, or name is NULL

Returns CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE if the field contains more than a single element

Returns CUPHYHDF5_STATUS_INVALID_NAME if the structure does not contain a field with the given name

Returns CUPHYHDF5_STATUS_CONVERT_ERROR if conversion to the requested cuPHY element type is not possible, or if conversion failed (due to overflow/underflow), or if the file datatype cannot be represented by one of the available variant types.

Returns CUPHYHDF5_STATUS_SUCCESS if the query was successful.

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE CUPHYHDF5_STATUS_CONVERT_ERROR CUPHYHDF5_STATUS_INVALID_NAME

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString,cuphyHDF5GetStruct

cuphyHDF5ReadDataset()

cuphyHDF5Status_t cuphyHDF5ReadDataset	(	const cuphyTensorDescriptor_t	tensorDesc,
		void *	addr,
		hid_t	h5Dataset,
		cudaStream_t	strm
	)

Reads data from a source HDF5 dataset into a destination cuPHY tensor. The cuPHY tensor descriptor and an appropriately sized buffer must be allocated before this function is called. The buffer must be GPU addressable (i.e. either in device or pinned host memory). The cuphyHDF5GetDatasetInfo function can be called to obtain information on the HDF5 dataset.

Note that the destination tensor does not have to be the same as the cuPHY type that maps directly to the stored HDF5 datatype. Any conversion that is supported by the cuphyConvertTensor function will be supported by this function.

Parameters

tensorDesc	- descriptor for the destination tensor
addr	- destination address for the loaded data
h5Dataset	- source dataset
strm	- CUDA stream used to perform the read operation

Returns CUPHYHDF5_STATUS_INVALID_DATASET if h5Dataset < 0.

Returns CUPHYHDF5_STATUS_INVALID_TENSOR_DESC if tensorDesc is invalid.

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if dimBufferSize > 0 and outputDimensions is NULL.

Returns CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE if dimBufferSize is less than the HDF5 dataspace rank

Returns CUPHYHDF5_STATUS_DATATYPE_ERROR if the data type of the HDF5 dataset cannot be represented by a cuPHY tensor element type

Returns CUPHYHDF5_STATUS_DATASPACE_ERROR if the HDF5 dataspace cannot be queried

Returns CUPHYHDF5_STATUS_UNSUPPORTED_RANK if the HDF5 dataspace is larger than the maximum rank supported by the cuPHY library

Returns CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE if one or more of the HDF5 dataspace dimensions is larger than the maximum size supported by the cuPHY library

Returns CUPHYHDF5_STATUS_TENSOR_MISMATCH if the rank and/or dimensions of the given cuPHY tensor descriptor do not match those of the HDF5 dataset.

Returns CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE if a cuPHY tensor descriptor could not be created, or if the tensor descriptor fields could not be set.

Returns CUPHYHDF5_STATUS_READ_ERROR if the HDF5 library returned an error when a read operation was attempted.

Returns CUPHYHDF5_STATUS_CONVERT_ERROR if conversion from the HDF5 type to the given tensor type is not supported.

Returns CUPHYHDF5_STATUS_SUCCESS if the read was successful.

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_INVALID_TENSOR_DESC CUPHYHDF5_STATUS_INVALID_DATASET CUPHYHDF5_STATUS_DIMENSION_TOO_LARGE CUPHYHDF5_STATUS_UNSUPPORTED_RANK CUPHYHDF5_STATUS_DATASPACE_ERROR CUPHYHDF5_STATUS_DATATYPE_ERROR CUPHYHDF5_STATUS_INADEQUATE_BUFFER_SIZE CUPHYHDF5_STATUS_TENSOR_MISMATCH CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE CUPHYHDF5_STATUS_READ_ERROR CUPHYHDF5_STATUS_CONVERT_ERROR

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString,cuphyHDF5GetDatasetInfo

cuphyHDF5ReleaseStruct()

cuphyHDF5Status_t cuphyHDF5ReleaseStruct

(

cuphyHDF5Struct_t

s

)

Releases a reference to a cuPHY HDF5 structure handle

Parameters

s	- cuphy HDF5 structure handle

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if s is NULL

Returns CUPHYHDF5_STATUS_SUCCESS if the release was successful.

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString,cuphyHDF5GetStruct

cuphyHDF5WriteDataset()

cuphyHDF5Status_t cuphyHDF5WriteDataset	(	hid_t	h5LocationID,
		const char *	name,
		const cuphyTensorDescriptor_t	tensorDesc,
		const void *	addr,
		cudaStream_t	strm
	)

Writes data from a source cuPHY tensor to a destination HDF5 dataset.

Parameters

h5LocationID	- output HDF5 location (HDF5 root/group)
name	- name of output HDF5 dataset
tensorDesc	- input tensor descriptor
addr	- address for input data source
strm	- CUDA stream used to perform the write operation

Returns CUPHYHDF5_STATUS_INVALID_ARGUMENT if an of tensorDesc, addr, or name is NULL, or if h5LocationID < 0.

Returns CUPHYHDF5_STATUS_INVALID_TENSOR_DESC if the tensor descriptor cannot be queried.

Returns CUPHYHDF5_STATUS_DATATYPE_ERROR if the data type of the cuPHY tensor cannot be stored in an HDF5 dataset (either directly, or via conversion)

Returns CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE if a cuPHY tensor descriptor could not be created, or if the tensor descriptor fields could not be set.

Returns CUPHYHDF5_STATUS_ALLOC_FAILED if memory allocation for a host copy of the input tensor failed.

Returns CUPHYHDF5_STATUS_CONVERT_ERROR if conversion from the cuPHY tensor type to the HDF5 datatype failed.

Returns CUPHYHDF5_STATUS_DATASPACE_ERROR if an HDF5 dataspace could not be created.

Returns CUPHYHDF5_STATUS_DATASET_ERROR if an HDF5 dataset could not be created.

Returns CUPHYHDF5_STATUS_WRITE_ERROR if the HDF5 library returned an error when a write operation was attempted.

Returns CUPHYHDF5_STATUS_SUCCESS if the write was successful.

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_INVALID_TENSOR_DESC CUPHYHDF5_STATUS_DATATYPE_ERROR CUPHYHDF5_STATUS_DATASPACE_ERROR CUPHYHDF5_STATUS_DATASET_ERROR CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE CUPHYHDF5_STATUS_ALLOC_FAILED CUPHYHDF5_STATUS_WRITE_ERROR CUPHYHDF5_STATUS_CONVERT_ERROR

See also

cuphyHDF5Status_t,cuphyHDF5GetErrorString

cuphyHDF5WriteDatasetFromCPU()

cuphyHDF5Status_t cuphyHDF5WriteDatasetFromCPU	(	hid_t	h5LocationID,
		const char *	name,
		const cuphyDataType_t	type,
		const int32_t	size,
		void *	pData
	)

Writes data from a source CPU array to a destination HDF5 dataset.

Parameters

h5LocationID	- output HDF5 location (HDF5 root/group)
name	- name of output HDF5 dataset
type	- input data type
size	- input data size
pData	- input data array

Returns

CUPHYHDF5_STATUS_SUCCESS, CUPHYHDF5_STATUS_INVALID_ARGUMENT CUPHYHDF5_STATUS_INVALID_TENSOR_DESC CUPHYHDF5_STATUS_DATATYPE_ERROR CUPHYHDF5_STATUS_DATASPACE_ERROR CUPHYHDF5_STATUS_DATASET_ERROR CUPHYHDF5_STATUS_TENSOR_DESC_FAILURE CUPHYHDF5_STATUS_ALLOC_FAILED CUPHYHDF5_STATUS_WRITE_ERROR CUPHYHDF5_STATUS_CONVERT_ERROR