commonDx#

LIBMATHDX_VER_MAJOR#: libmathdx major version number.

LIBMATHDX_VER_MINOR#: libmathdx minor version number.

LIBMATHDX_VER_PATCH#: libmathdx patch version number.

LIBMATHDX_COMMIT#: libmathdx source commit SHA as a string.

commondxStatusType mathdxGetVersion(int *version)#

Returns the libmathdx version as a single integer.

Parameters:: version – [out] The version, encoded as 1000 * major + 100 * minor + patch
Returns:: COMMONDX_SUCCESS

commondxStatusType mathdxGetVersionEx( int *major, int *minor, int *patch )#

Returns the libmathdx version as a triplet of integers.

Parameters:

major – [out] The major version.
minor – [out] The minor version.
patch – [out] The patch version.

Returns:

COMMONDX_SUCCESS

commondxStatusType mathdxGetPackageVersion( int *year, int *month, int *patch )#

Returns the corresponding MathDx package “calver” version as a triplet of integers.

Parameters:

year – [out] The year
month – [out] The month
patch – [out] The patch version.

Returns:

COMMONDX_SUCCESS

commondxStatusType mathdxGetCommit(const char **commit)#

Returns the libmathdx source commit as a string. This function does not allocate. The returned string must not be mutated or free.

Parameters:: commit – [out] A pointer to C-string containing the library commit hash as a string.
Returns:: COMMONDX_SUCCESS

typedef long long int commondxCode#

A handle to some compiled code.

Compiled code generally contains one or more device function, and is specified by the code type (e.g. SASS, PTX, LTO - commondxCodeContainer_t) and the compute capability (in the form of an integer, e.g. 800 for CC 8.0).

Compiled code can be genrated by a call to cublasdxFinalizeCode, cufftdxFinalizeCode or cusolverdxFinalizeCode.

enum commondxValueType_t#

The set of value types supported by the library.

Note that, for complex numbers, this combines real and imaginary part, and that all complex numbers are overaligned on their size.

Values:

enumerator COMMONDX_R_8F_E5M2#: Equivalent to __nv_fp8_e5m2. Size: 1B, alignment: 1B

enumerator COMMONDX_C_8F_E5M2#: Equivalent to 2x__nv_fp8_e5m2. Size: 2B, alignment: 2B (overaligned)

enumerator COMMONDX_R_8F_E4M3#: Equivalent to __nv_fp8_e4m3. Size: 1B, alignment: 1B

enumerator COMMONDX_C_8F_E4M3#: Equivalent to 2x__nv_fp8_e4m3. Size: 2B, alignment: 2B (overaligned)

enumerator COMMONDX_R_16BF#: Equivalent to __nv_bfloat16. Size: 2B, alignment: 2B

enumerator COMMONDX_C_16BF#: Equivalent to 2x__nv_bfloat16. Size: 4B, alignment: 4B (overaligned)

enumerator COMMONDX_R_16F2#: Equivalent to __half2. Size: 4B, alignment: 4B

enumerator COMMONDX_R_16F#: Equivalent to __half. Size: 2B, alignment: 2B

enumerator COMMONDX_C_16F#: Equivalent to 2x__half. Size: 4B, alignment: 4B (overaligned)

enumerator COMMONDX_C_16F2#: Equivalent to 2x__half2. Size: 8B, alignment: 8B (overaligned)

enumerator COMMONDX_R_32TF#: Equivalent to tf32. Size: 4B, alignment: 4B

enumerator COMMONDX_C_32TF#: Equivalent to 2xtf32. Size: 8B, alignment: 8B (overaligned)

enumerator COMMONDX_R_32F#: Equivalent to float. Size: 4B, alignment: 4B

enumerator COMMONDX_C_32F#: Equivalent to 2xfloat. Size: 8B, alignment: 8B (overaligned)

enumerator COMMONDX_R_64F#: Equivalent to double. Size: 8B, alignment: 8B

enumerator COMMONDX_C_64F#: Equivalent to 2xdouble. Size: 16B, alignment: 16B (overaligned)

enumerator COMMONDX_R_8I#: Equivalent to int8_t. Size 1B, alignment: 1B

enumerator COMMONDX_C_8I#: Equivalent to 2xint8_t. Size 2B, alignment: 2B (overaligned)

enumerator COMMONDX_R_16I#: Equivalent to int16_t. Size 2B, alignment: 2B

enumerator COMMONDX_C_16I#: Equivalent to 2xint16_t. Size 4B, alignment: 4B (overaligned)

enumerator COMMONDX_R_32I#: Equivalent to int32_t. Size 4B, alignment: 4B

enumerator COMMONDX_C_32I#: Equivalent to 2xint32_t. Size 8B, alignment: 8B (overaligned)

enumerator COMMONDX_R_64I#: Equivalent to int64_t. Size 8B, alignment: 8B

enumerator COMMONDX_C_64I#: Equivalent to 2xint64_t. Size 16B, alignment: 16B (overaligned)

enumerator COMMONDX_R_8UI#: Equivalent to uint8_t. Size 1B, alignment: 1B

enumerator COMMONDX_C_8UI#: Equivalent to 2xuint8_t. Size 2B, alignment: 2B (overaligned)

enumerator COMMONDX_R_16UI#: Equivalent to uint16_t. Size 2B, alignment: 2B

enumerator COMMONDX_C_16UI#: Equivalent to 2xuint16_t. Size 4B, alignment: 4B (overaligned)

enumerator COMMONDX_R_32UI#: Equivalent to uint32_t. Size 4B, alignment: 4B

enumerator COMMONDX_C_32UI#: Equivalent to 2xuint32_t. Size 8B, alignment: 8B (overaligned)

enumerator COMMONDX_R_64UI#: Equivalent to uint64_t. Size 8B, alignment: 8B

enumerator COMMONDX_C_64UI#: Equivalent to 2xuint64_t. Size 16B, alignment: 16B (overaligned)

enum commondxStatusType_t#

The set of status values that can be returned by APIs defined in the library.

Values:

enumerator COMMONDX_SUCCESS#: Success

enumerator COMMONDX_INVALID_VALUE#: One of the input values is not in the allowed range or is otherwise invalid

enumerator COMMONDX_INTERNAL_ERROR#: Library internal error

enumerator COMMONDX_COMPILATION_ERROR#: Compilation did not complete successfully

enumerator COMMONDX_CUFFT_ERROR#: Library dependency error

enumerator COMMONDX_FILE_ERROR#: Filesystem error (eg not enough space or no sufficient permissions)

enum commondxPrecision_t#

The set of precisions supported by the library.

For the actual input and output value types, see commondxValueType_t

Values:

enumerator COMMONDX_PRECISION_F8_E5M2#: Equivalent to __nv_fp8_e5m2

enumerator COMMONDX_PRECISION_F8_E4M3#: Equivalent to __nv_fp8_e4m3

enumerator COMMONDX_PRECISION_BF16#: Equivalent to __nv_bfloat16

enumerator COMMONDX_PRECISION_F16#: Equivalent to __half

enumerator COMMONDX_PRECISION_TF32#: Equivalent to tfloat32

enumerator COMMONDX_PRECISION_F32#: Equivalent to float

enumerator COMMONDX_PRECISION_F64#: Equivalent to double

enumerator COMMONDX_PRECISION_I8#: Equivalent to int8_t

enumerator COMMONDX_PRECISION_I16#: Equivalent to int16_t

enumerator COMMONDX_PRECISION_I32#: Equivalent to int32_t

enumerator COMMONDX_PRECISION_I64#: Equivalent to int64_t

enumerator COMMONDX_PRECISION_UI8#: Equivalent to uint8_t

enumerator COMMONDX_PRECISION_UI16#: Equivalent to uint16_t

enumerator COMMONDX_PRECISION_UI32#: Equivalent to uint32_t

enumerator COMMONDX_PRECISION_UI64#: Equivalent to uint64_t

enum commondxOption_t#

Options to tweak code generation.

Values:

enumerator COMMONDX_OPTION_SYMBOL_NAME#: Symbol to wrap the device function in (default is autogenerated). Associated value must be A C-string.

enumerator COMMONDX_OPTION_TARGET_SM#

Target SM. Associated value must be an integer, e.g. 800 for SM80 or a pair (integer, modifier) where modifier is an enum of type commondxArchModifier_t .

See commondxSetCodeOptionInt64 and commondxSetCodeOptionInt64s

enumerator COMMONDX_OPTION_CODE_CONTAINER#: Code container type (e.g. PTX, LTO, Cubin (SASS), FATBIN). Associated value must be a value of commondxCodeContainer_t

enumerator COMMONDX_OPTION_CODE_ISA#: Code ISA (e.g. 12.3 for LTO). Associated value must be an integer, e.g. 12030 for 12.3

enumerator COMMONDX_OPTION_EXTRA_NVRTC_ARGS#: Extra arguments passed to NVRTC. Must be one or more C-string. See commondxSetCodeOptionStr and commondxSetCodeOptionStrs .

enumerator COMMONDX_OPTION_TARGET_CODE#: What code to generate (PTX or LTO). Associated value must be a value of commondxCodeType

enum commondxExecution_t#

The set of execution modes supported by the library.

Values:

enumerator COMMONDX_EXECUTION_THREAD#: Thread APIs. All threads are independant, divergent control flow is allowed.

enumerator COMMONDX_EXECUTION_BLOCK#: Block APIs. All threads in the block cooperate, and all must call the device function.

enumerator COMMONDX_EXECUTION_WARP#: Warp APIs. All threads in a single warp cooperate. Participating threads must start at laneid 0.

enum commondxCodeContainer_t#

The set of device code container types supported by the library. See commondxOption_t::COMMONDX_OPTION_CODE_CONTAINER.

Values:

enumerator COMMONDX_CODE_CONTAINER_LTOIR#: .ltoir, aka -dlto -ltoir with NVCC and NVRTC

enumerator COMMONDX_CODE_CONTAINER_FATBIN#: .fatbin, aka -fatbin with NVCC

enumerator COMMONDX_CODE_CONTAINER_PTX#: .ptx, PTX textual format

enum commondxArchModifier_t#

The set of compute feature to target. See COMMONDX_OPTION_TARGET_SM .

Values:

enumerator COMMONDX_ARCH_MODIFIER_GENERIC#: Target the baseline set of compute features

enumerator COMMONDX_ARCH_MODIFIER_ARCH_SPECIFIC#: Target the arch specific set of compute features

enumerator COMMONDX_ARCH_MODIFIER_FAMILY_SPECIFIC#: Target the family specific set of compute features

enum commondxCodeType_t#

The set of code types supported by the library. See commondxOption_t::COMMONDX_OPTION_TARGET_CODE.

Values:

enumerator COMMONDX_CODE_TYPE_LTO#: LTO

enumerator COMMONDX_CODE_TYPE_PTX#: PTX

commondxStatusType commondxCreateCode(commondxCode *code)#

Creates a code handle.

Parameters:: code – [out] A pointer to the output code handle.
Returns:: COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxSetCodeOptionInt64( commondxCode code, commondxOption option, long long int value )#

Set an option on a code handle.

Parameters:

code – [in] A code handle from commondxCreateCode
option – [in] The option to set the code to
value – [in] A corresponding value for the selected option

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxSetCodeOptionInt64s( commondxCode code, commondxOption option, size_t count, long long int *values )#

Set an option on a code handle.

Parameters:

code – [in] A code handle from commondxCreateCode.
option – [in] The option to set the code to.
count – [in] The length of the array.
values – [in] A pointer to count entries.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxSetCodeOptionStr( commondxCode code, commondxOption option, const char *value )#

Set a C-string option on a code handle.

Parameters:

code – [in] A code handle from commondxCreateCode.
option – [in] The option to set the code to.
value – [in] A C-string. Cannot be NULL.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxSetCodeOptionStrs(

commondxCode code,

commondxOption option,

size_t count,

const char **values

)#

Set one or more C-string option on a code handle.

Parameters:

code – [in] A code handle from commondxCreateCode.
option – [in] The option to set the code to.
count – [in] The number of C-strings to set.
values – [in] A pointer to an array of count C-strings.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeOptionInt64( commondxCode code, commondxOption option, long long int *value )#

Get option from a code handle.

Parameters:

code – [in] A code handle from commondxCreateCode
option – [in] The option to get
value – [out] The option value.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeOptionsInt64s( commondxCode code, commondxOption option, size_t size, long long int *array )#

Get options (as an array) from a code handle, with one option per output code.

Parameters:

code – [in] A code handle from commondxCreateCode
option – [in] The option to get
size – [in] The array size, as result from commondxGetCodeNumLTOIRs
array – [out] A pointer to the beginning of the output array. Must be a pointer to a buffer of at least size elements.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeLTOIRSize( commondxCode code, size_t *size )#

Extract the LTOIR size, in bytes.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [out] The LTOIR size, in bytes.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeLTOIR( commondxCode code, size_t size, void *out )#

Extract the LTOIR.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [in] The LTOIR size, as returned by commondxGetCodeLTOIRSize
out – [out] The LTOIR. Must be a pointer to a buffer of at least size byte.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeNumLTOIRs( commondxCode code, size_t *size )#

Returns the number the LTOIR chunks.

Some code produce more than one LTOIR. In this case, this function must be used to retreive the number of LTOIR’s.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [out] The number of LTOIR chunks.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeLTOIRSizes( commondxCode code, size_t size, size_t *out )#

Returns the size of all LTOIR chunks.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [in] The number of LTOIR chunks, as returned by commondxGetCodeNumLTOIRs
out – [out] On output, out[i] is the size, in byte, of the ith LTOIR chunk.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodeLTOIRs(

commondxCode code,

size_t size,

void **out

)#

Returns all LTOIR chunks.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [in] The number of LTOIR chunks, as returned by commondxGetCodeNumLTOIRs
out – [out] On output, out[i] is filled with the ith LTOIR chunk. out[i] must point to a buffer of at least size[i] bytes, with size the output of commondxGetCodeLTOIRSizes

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodePTXSize( commondxCode code, size_t *size )#

Extract the PTX size, in bytes.

The PTX is a null-terminated string, and the size includes the null terminator.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [out] The PTX size, in bytes (including null terminator).

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetCodePTX( commondxCode code, size_t size, void *out )#

Extract the PTX.

The PTX is returned as a null-terminated string.

Parameters:

code – [in] A code handle from commondxCreateCode
size – [in] The PTX size, as returned by commondxGetCodePTXSize
out – [out] The PTX. Must be a pointer to a buffer of at least size bytes.

Returns:

COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxDestroyCode(commondxCode code)#

Destroys a code handle.

Parameters:: code – [in] A code handle from commondxCreateCode
Returns:: COMMONDX_SUCCESS on success, or an error.

commondxStatusType commondxGetLastErrorStrSize(size_t *size)#

Returns the size of the last error string. See commondxGetLastErrorStr.

Parameters:: size – [out] The size in byte of the last error C-string, including the null terminator.
Returns:: COMMONDX_SUCCESS on success or COMMONDX_INVALID_VALUE if no error is available to be returned.

commondxStatusType commondxGetLastErrorStr( commondxStatusType *code, size_t size, char *value )#

Returns the last error as a human readable C-string.

This function will return the last error encountered by the current host thread. Current this only supports COMMONDX_COMPILATION_ERROR. Setting the LIBMATHDX_LOG_LEVEL environment variable to 5 in the environment will also display more error logs.

Parameters:

code – [out] The error code associated with the last error.
size – [in] The size in bytes of the buffer value. See commondxGetLastErrorStrSize .
value – [out] Upon return, will point to a C-string holding the error description.

Returns:

COMMONDX_SUCCESS on success or COMMONDX_INVALID_VALUE if no error is available to be returned.

const char *commondxStatusToStr(commondxStatusType status)#

Convert a status enum to a human readable C-string.

Parameters:: status – [in] The status enum to convert
Returns:: A short C-string describing the enum. This C-string should be not free’ed by the caller.

const char *commondxValueTypeToStr(commondxValueType value_type)#

Convert a value type enum to a human readable C-string.

Parameters:: value_type – [in] The value type enum to convert
Returns:: The C-string

const char *commondxPrecisionToStr(commondxPrecision precision)#

Convert a precision enum to a human readable C-string.

Parameters:: precision – [in] The precision enum to convert
Returns:: The C-string

const char *commondxOptionToStr(commondxOption option)#

Convert an option enum to a human readable C-string.

Parameters:: option – [in] The option enum to convert
Returns:: The C-string

const char *commondxExecutionToStr(commondxExecution execution)#

Convert an execution enum to a human readable C-string.

Parameters:: execution – [in] The execution enum to convert
Returns:: The C-string

const char *commondxCodeContainerToStr( commondxCodeContainer container )#

Convert a code container type enum to a human readable C-string.

Parameters:: container – [in] The code container type enum to convert
Returns:: The C-string

const char *commondxArchModifierToStr(commondxArchModifier modifier)#

Converts an arch modifier enum to a human readable C-string.

Parameters:: modifier – [in] The arch modifier enum to convert
Returns:: The C-string

const char *commondxCodeTypeToStr(commondxCodeType code)#

Convert a code type enum to a human readable C-string.

Parameters:: code – [in] The code type enum to convert
Returns:: The C-string