Tensor Descriptors

This section describes the tensor descriptor functions of the cuPHY application programming interface. More...

Data Structures
struct	_cuphyTensorPrm
struct	cuphyTensorInfo1_t

Typedefs
typedef struct cuphyTensorDescriptor *	cuphyTensorDescriptor_t

Functions
cuphyStatus_t	cuphyCreateTensorDescriptor (cuphyTensorDescriptor_t *ptensorDesc)
	Allocates and initializes a cuPHY tensor descriptor. More...
cuphyStatus_t	cuphyDestroyTensorDescriptor (cuphyTensorDescriptor_t tensorDesc)
	Destroys a cuPHY tensor descriptor. More...
const char *	cuphyGetDataTypeString (cuphyDataType_t type)
	Returns a string value for a given data type. More...
cuphyStatus_t	cuphyGetTensorDescriptor (cuphyTensorDescriptor_t tensorDesc, int numDimsRequested, cuphyDataType_t *dataType, int *numDims, int dimensions[], int strides[])
	Query values for the internal state of a cuPHY tensor descriptor. More...
cuphyStatus_t	cuphyGetTensorSizeInBytes (cuphyTensorDescriptor_t tensorDesc, size_t *psz)
	Returns the size of an allocation for a tensor descriptor. More...
cuphyStatus_t	cuphySetTensorDescriptor (cuphyTensorDescriptor_t tensorDesc, cuphyDataType_t type, int numDimensions, const int dimensions[], const int strides[], unsigned int flags)
	Provide values for the internal state of a cuPHY tensor descriptor. More...

Detailed Description

Typedef Documentation

cuphyTensorDescriptor_t

typedef struct cuphyTensorDescriptor* cuphyTensorDescriptor_t

cuPHY Tensor Descriptor handle

Function Documentation

cuphyCreateTensorDescriptor()

cuphyStatus_t cuphyCreateTensorDescriptor

(

cuphyTensorDescriptor_t *

ptensorDesc

)

Allocates a cuPHY tensor descriptor and returns a handle in the address provided by the caller.

The allocated descriptor will have type CUPHY_VOID, and (in most cases) cannot be used for operations until the tensor state has been initialized by calling cuphySetTensorDescriptor.

Upon successful return the tensor descriptor will have a rank of 0.

Returns CUPHY_STATUS_INVALID_ARGUMENT if ptensorDesc is NULL.

Returns CUPHY_STATUS_ALLOC_FAILED if a tensor descriptor cannot be allocated on the host.

Returns CUPHY_STATUS_SUCCESS if allocation and initialization were successful.

Parameters

ptensorDesc

- Address for the new cuphyTensorDescriptor_t instance

Returns

CUPHY_STATUS_SUCCESS, CUPHY_STATUS_ALLOC_FAILED, CUPHY_STATUS_INVALID_ARGUMENT

See also

cuphyStatus_t,cuphyGetErrorName,cuphyGetErrorString

cuphyDestroyTensorDescriptor()

cuphyStatus_t cuphyDestroyTensorDescriptor

(

cuphyTensorDescriptor_t

tensorDesc

)

Destroys a cuPHY tensor descriptor that was previously allocated by a call to cuphyCreateTensorDescriptor. The handle provided to this function should not be used for any operations after this function returns.

Returns CUPHY_STATUS_INVALID_ARGUMENT if tensorDesc is NULL.

Returns CUPHY_STATUS_SUCCESS if destruction was successful.

Parameters

tensorDesc

- previously allocated cuphyTensorDescriptor_t instance

Returns

CUPHY_STATUS_SUCCESS, CUPHY_STATUS_INVALID_ARGUMENT

See also

cuphyStatus_t,cuphyCreateTensorDescriptor

cuphyGetDataTypeString()

const char* cuphyGetDataTypeString

(

cuphyDataType_t

type

)

Returns a string for the given cuphyDataType_t, or "UNKNOWN_TYPE" if the type is unknown.

Parameters

type	- data type (cuphyDataType_t)

Returns

char* pointer to a NULL-terminated string

See also

cuphyDataType_t

cuphyGetTensorDescriptor()

cuphyStatus_t cuphyGetTensorDescriptor	(	cuphyTensorDescriptor_t	tensorDesc,
		int	numDimsRequested,
		cuphyDataType_t *	dataType,
		int *	numDims,
		int	dimensions[],
		int	strides[]
	)

Retrieves the internal state of a tensor descriptor that was created via the cuphyCreateTensorDescriptor function and initialized with the cuphySetTensorDescriptor function

Parameters

tensorDesc	- previously allocated cuphyTensorDescriptor_t instance
numDimsRequested	- the size of the array provided by the dimensions parameter, and the strides parameter (if non-NULL)
dataType	- address for the returned cuphyDataType_t (may be NULL)
numDims	- output address for the rank of the tensor descriptor (may be NULL)
dimensions	- output location for dimensions for the tensor descriptor
strides	- output location for tensor strides (may be NULL)

Returns CUPHY_STATUS_INVALID_ARGUMENT if tensorDesc is NULL, or if numDimsRequested > 0 and dimensions is NULL.

Returns CUPHY_STATUS_SUCCESS if the state query was successful.

Returns

CUPHY_STATUS_SUCCESS, CUPHY_STATUS_INVALID_ARGUMENT

See also

cuphyStatus_t,cuphyCreateTensorDescriptor,cuphySetTensorDescriptor

cuphyGetTensorSizeInBytes()

cuphyStatus_t cuphyGetTensorSizeInBytes	(	cuphyTensorDescriptor_t	tensorDesc,
		size_t *	psz
	)

Calculates the size (in bytes) of an allocation that would be required to represent a tensor described by the given descriptor.

Parameters

tensorDesc	- previously allocated cuphyTensorDescriptor_t instance
psz	- address to hold the calculated size output

Returns CUPHY_STATUS_INVALID_ARGUMENT if tensorDesc is NULL, or if psz is NULL.

Returns CUPHY_STATUS_SUCCESS if the size calculation was successful.

Returns

CUPHY_STATUS_SUCCESS, CUPHY_STATUS_INVALID_ARGUMENT

See also

cuphyStatus_t,cuphyCreateTensorDescriptor,cuphySetTensorDescriptor

cuphySetTensorDescriptor()

cuphyStatus_t cuphySetTensorDescriptor	(	cuphyTensorDescriptor_t	tensorDesc,
		cuphyDataType_t	type,
		int	numDimensions,
		const int	dimensions[],
		const int	strides[],
		unsigned int	flags
	)

Sets the internal state of a tensor descriptor that was created via the cuphyCreateTensorDescriptor function.

Note that a tensor descriptor is not associated with a specific memory allocation or address. A tensor descriptor provides the cuPHY library with values that can be used "interpret" a range of memory as a tensor with the specified properties. A tensor descriptor can be used with multiple different addresses, and an address can be accessed with multiple different tensor descriptors.

Parameters

tensorDesc	- previously allocated cuphyTensorDescriptor_t instance
type	- cuphyDataType_t enumeration with the desired tensor element type
numDimensions	- the desired tensor rank
dimensions	- an array of dimensions for the tensor descriptor
strides	- an array of strides (may be NULL)
flags	- tensor descriptor flags

Returns CUPHY_STATUS_INVALID_ARGUMENT if:

• tensorDesc is NULL.
• dimensions is NULL.
• numDimensions <= 0.
• numDimensions > CUPHY_DIM_MAX.
• type is CUPHY_VOID.
• Any element of the dimensions array is less than equal to 0.

Returns CUPHY_STATUS_SUCCESS if the state update was successful.

The stride of a given dimension describes the distance between two elements that differ by 1 in that dimension. For example, a 2-dimensional, (10 x 8) matrix with no padding would have a stride[0] = 1 and stride[1] = 10.

There is no requirement that strides be in ascending order.

The flags argument can be used to request that the cuPHY library automatically calculate values for the tensor strides, as a convenience. The values allowed for flags are:

• CUPHY_TENSOR_ALIGN_DEFAULT: If strides are provided, they will be used. Otherwise, set the strides for tight packing.
• CUPHY_TENSOR_ALIGN_TIGHT: Set the strides so that no padding is present. stride[0] = 1, and stride[i] = dimensions[i - 1] * strides[i - 1]
• CUPHY_TENSOR_ALIGN_COALESCE: Set the strides for the first dimension based on the element type, so that the stride (in bytes) will be a multiple of 128.

Returns

CUPHY_STATUS_SUCCESS, CUPHY_STATUS_INVALID_ARGUMENT

See also

cuphyStatus_t,cuphyCreateTensorDescriptor