Skip to main content

MUSA Driver API Reference

1. Introduction​

The MUSA Driver API is the low-level mu* interface for applications and libraries that need direct control over devices, contexts, modules, memory, streams, events, graphs, and interoperability objects.

This reference describes the MUSA Driver APIs supported in MUSA SDK 5.2.0. Use it as the compatibility reference for the functions, types, structures, fields, constants, and result values documented here.

Note: Some Driver API declarations may appear in the headers but are not described in this reference. These declarations are experimental in MUSA SDK 5.2.0 and are provided for reference only.

2. Using the Driver API​

Start with the Runtime API when you want the application-level musa* interface. Use this Driver reference when you need lower-level mu* control, or when a Runtime entry points to a Driver-level object or equivalent.

Driver API use depends on initialization and context state. Review Initialization, Primary Context Management, and Context Management before allocating memory, loading modules, launching work, or sharing resources across APIs.

Synchronization behavior, asynchronous error reporting, object lifetime, and thread-safety constraints are documented in the function entries. For Stream Management, Event Management, Memory Management, Execution Control, and Graph Management APIs, read the Returns and Note sections before relying on host-side completion or object sharing.

Use Version Management for Driver version checks and Driver Entry Point Access to resolve Driver symbols dynamically.

3. Modules​

The API reference is organized by capability module.

Module List

3.1 Error Handling​

muGetErrorString​

MUresult muGetErrorString(MUresult error, const char **pStr)

Description

  • Gets the string description of an error code.
  • Sets *pStr to the address of a NULL-terminated string description of the error code error. If the error code is not recognized, MUSA_ERROR_INVALID_VALUE will be returned and *pStr will be set to the NULL address.

Parameters

  • error (MUresult): Error code to convert to string
  • pStr (const char **): Address of the string pointer.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

See also

muGetErrorName​

MUresult muGetErrorName(MUresult error, const char **pStr)

Description

  • Gets the string representation of an error code enum name.
  • Sets *pStr to the address of a NULL-terminated string representation of the name of the enum error code error. If the error code is not recognized, MUSA_ERROR_INVALID_VALUE will be returned and *pStr will be set to the NULL address.

Parameters

  • error (MUresult): Error code to convert to string
  • pStr (const char **): Address of the string pointer.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

See also

3.2 Initialization​

muInit​

MUresult muInit(unsigned int Flags)

Description

  • Initialize the MUSA driver API Initializes the driver API and must be called before any other function from the driver API in the current process. Currently, the Flags parameter must be 0. If muInit() has not been called, any function from the driver API will return MUSA_ERROR_NOT_INITIALIZED.
  • Note: muInit preloads various libraries needed for JIT compilation. To opt-out of this behavior, set the environment variable MUSA_FORCE_PRELOAD_LIBRARIES=0. MUSA will lazily load JIT libraries as needed. To disable JIT entirely, set the environment variable MUSA_DISABLE_JIT=1.

Parameters

  • Flags (unsigned int): Initialization flag for MUSA.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_SYSTEM_DRIVER_MISMATCH, MUSA_ERROR_COMPAT_NOT_SUPPORTED_ON_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

3.3 Version Management​

muDriverGetVersion​

MUresult muDriverGetVersion(int *driverVersion)

Description

  • Returns the latest MUSA version supported by driver.
  • Returns in *driverVersion the version of MUSA supported by the driver. The version is returned as (1000 major + 10 minor). For example, MUSA 9.2 would be represented by 9020.
  • This function automatically returns MUSA_ERROR_INVALID_VALUE if driverVersion is NULL.

Parameters

  • driverVersion (int *): Returns the MUSA driver version

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.4 Device Management​

muDeviceGet​

MUresult muDeviceGet(MUdevice *device, int ordinal)

Description

  • Returns a handle to a compute device.
  • Returns in *device a device handle given an ordinal in the range [0, muDeviceGetCount()-1].

Parameters

  • device (MUdevice *): Returned device handle
  • ordinal (int): Device number to get handle for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetCount​

MUresult muDeviceGetCount(int *count)

Description

  • Returns the number of compute-capable devices.
  • Returns in *count the number of devices with compute capability greater than or equal to 2.0 that are available for execution. If there is no such device, muDeviceGetCount() returns 0.

Parameters

  • count (int *): Returned number of compute-capable devices

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetName​

MUresult muDeviceGetName(char *name, int len, MUdevice dev)

Description

  • Returns an identifier string for the device.
  • Returns an ASCII string identifying the device dev in the NULL-terminated string pointed to by name. len specifies the maximum length of the string that may be returned.

Parameters

  • name (char *): Returned identifier string for the device
  • len (int): Maximum length of string to store in name
  • dev (MUdevice): Device to get identifier string for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetUuid​

MUresult muDeviceGetUuid(MUuuid *uuid, MUdevice dev)

Description

  • Return an UUID for the device.
  • Note there is a later version of this API, muDeviceGetUuid_v2. It will supplant this version in 12.0, which is retained for minor version compatibility.
  • Returns 16-octets identifying the device dev in the structure pointed by the uuid.

Parameters

  • uuid (MUuuid *): Returned UUID
  • dev (MUdevice): Device to get identifier string for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetUuid_v2​

MUresult muDeviceGetUuid_v2(MUuuid *uuid, MUdevice dev)

Description

  • Return an UUID for the device (11.4+)
  • Returns 16-octets identifying the device dev in the structure pointed by the uuid. If the device is in MIG mode, returns its MIG UUID which uniquely identifies the subscribed MIG compute instance.

Parameters

  • uuid (MUuuid *): Returned UUID
  • dev (MUdevice): Device to get identifier string for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceTotalMem​

MUresult muDeviceTotalMem(size_t *bytes, MUdevice dev)

Description

  • Return an LUID and device node mask for the device.
  • Return identifying information (luid and deviceNodeMask) to allow matching device with graphics APIs.
  • Returns in *bytes the total amount of memory available on the device dev in bytes.

Parameters

  • bytes (size_t *): Returned memory available on device in bytes
  • dev (MUdevice): Device handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • Additional exported symbol names in scope: muDeviceTotalMem_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetTexture1DLinearMaxWidth​

MUresult muDeviceGetTexture1DLinearMaxWidth(size_t *maxWidthInElements, MUarray_format format, unsigned numChannels, MUdevice dev)

Description

  • Returns the maximum number of elements allocatable in a 1D linear texture for a given texture element size.
  • Returns in maxWidthInElements the maximum number of texture elements allocatable in a 1D linear texture for given format and numChannels.

Parameters

  • maxWidthInElements (size_t *): Returned maximum number of texture elements allocatable for given format and numChannels.
  • format (MUarray_format): Texture format.
  • numChannels (unsigned): Number of channels per texture element.
  • dev (MUdevice): Device handle.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetAttribute​

MUresult muDeviceGetAttribute(int *pi, MUdevice_attribute attrib, MUdevice dev)

Description

  • Returns information about the device.
  • Returns in *pi the integer value of the attribute attrib on device dev. The supported attributes are: MU_DEVICE_ATTRIBUTE_MAX_THREADS_PER_BLOCK: Maximum number of threads per block; MU_DEVICE_ATTRIBUTE_MAX_BLOCK_DIM_X: Maximum x-dimension of a block MU_DEVICE_ATTRIBUTE_MAX_BLOCK_DIM_Y: Maximum y-dimension of a block MU_DEVICE_ATTRIBUTE_MAX_BLOCK_DIM_Z: Maximum z-dimension of a block MU_DEVICE_ATTRIBUTE_MAX_GRID_DIM_X: Maximum x-dimension of a grid MU_DEVICE_ATTRIBUTE_MAX_GRID_DIM_Y: Maximum y-dimension of a grid MU_DEVICE_ATTRIBUTE_MAX_GRID_DIM_Z: Maximum z-dimension of a grid MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_BLOCK: Maximum amount of shared memory available to a thread block in bytes MU_DEVICE_ATTRIBUTE_TOTAL_CONSTANT_MEMORY: Memory available on device for constant variables in a MUSA C kernel in bytes MU_DEVICE_ATTRIBUTE_WARP_SIZE: Warp size in threads MU_DEVICE_ATTRIBUTE_MAX_PITCH: Maximum pitch in bytes allowed by the memory copy functions that involve memory regions allocated through muMemAllocPitch() MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_WIDTH: Maximum 1D texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_LINEAR_WIDTH: Maximum width for a 1D texture bound to linear memory MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_MIPMAPPED_WIDTH: Maximum mipmapped 1D texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_WIDTH: Maximum 2D texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_HEIGHT: Maximum 2D texture height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_WIDTH: Maximum width for a 2D texture bound to linear memory MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_HEIGHT: Maximum height for a 2D texture bound to linear memory MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_PITCH: Maximum pitch in bytes for a 2D texture bound to linear memory MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_MIPMAPPED_WIDTH: Maximum mipmapped 2D texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_MIPMAPPED_HEIGHT: Maximum mipmapped 2D texture height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_WIDTH: Maximum 3D texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_HEIGHT: Maximum 3D texture height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_DEPTH: Maximum 3D texture depth MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_WIDTH_ALTERNATE: Alternate maximum 3D texture width, 0 if no alternate maximum 3D texture size is supported MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_HEIGHT_ALTERNATE: Alternate maximum 3D texture height, 0 if no alternate maximum 3D texture size is supported MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE3D_DEPTH_ALTERNATE: Alternate maximum 3D texture depth, 0 if no alternate maximum 3D texture size is supported MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURECUBEMAP_WIDTH: Maximum cubemap texture width or height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_LAYERED_WIDTH: Maximum 1D layered texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_LAYERED_LAYERS: Maximum layers in a 1D layered texture MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LAYERED_WIDTH: Maximum 2D layered texture width MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LAYERED_HEIGHT: Maximum 2D layered texture height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LAYERED_LAYERS: Maximum layers in a 2D layered texture MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURECUBEMAP_LAYERED_WIDTH: Maximum cubemap layered texture width or height MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURECUBEMAP_LAYERED_LAYERS: Maximum layers in a cubemap layered texture MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE1D_WIDTH: Maximum 1D surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE2D_WIDTH: Maximum 2D surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE2D_HEIGHT: Maximum 2D surface height MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE3D_WIDTH: Maximum 3D surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE3D_HEIGHT: Maximum 3D surface height MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE3D_DEPTH: Maximum 3D surface depth MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE1D_LAYERED_WIDTH: Maximum 1D layered surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE1D_LAYERED_LAYERS: Maximum layers in a 1D layered surface MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE2D_LAYERED_WIDTH: Maximum 2D layered surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE2D_LAYERED_HEIGHT: Maximum 2D layered surface height MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACE2D_LAYERED_LAYERS: Maximum layers in a 2D layered surface MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACECUBEMAP_WIDTH: Maximum cubemap surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACECUBEMAP_LAYERED_WIDTH: Maximum cubemap layered surface width MU_DEVICE_ATTRIBUTE_MAXIMUM_SURFACECUBEMAP_LAYERED_LAYERS: Maximum layers in a cubemap layered surface MU_DEVICE_ATTRIBUTE_MAX_REGISTERS_PER_BLOCK: Maximum number of 32-bit registers available to a thread block MU_DEVICE_ATTRIBUTE_CLOCK_RATE: The typical clock frequency in kilohertz MU_DEVICE_ATTRIBUTE_TEXTURE_ALIGNMENT: Alignment requirement; texture base addresses aligned to textureAlign bytes do not need an offset applied to texture fetches MU_DEVICE_ATTRIBUTE_TEXTURE_PITCH_ALIGNMENT: Pitch alignment requirement for 2D texture references bound to pitched memory MU_DEVICE_ATTRIBUTE_GPU_OVERLAP: 1 if the device can concurrently copy memory between host and device while executing a kernel, or 0 if not MU_DEVICE_ATTRIBUTE_MULTIPROCESSOR_COUNT: Number of multiprocessors on the device MU_DEVICE_ATTRIBUTE_KERNEL_EXEC_TIMEOUT: 1 if there is a run time limit for kernels executed on the device, or 0 if not MU_DEVICE_ATTRIBUTE_INTEGRATED: 1 if the device is integrated with the memory subsystem, or 0 if not MU_DEVICE_ATTRIBUTE_CAN_MAP_HOST_MEMORY: 1 if the device can map host memory into the MUSA address space, or 0 if not MU_DEVICE_ATTRIBUTE_COMPUTE_MODE: Compute mode that device is currently in. Available modes are as follows: MU_COMPUTEMODE_DEFAULT: Default mode - Device is not restricted and can have multiple MUSA contexts present at a single time. MU_COMPUTEMODE_PROHIBITED: Compute-prohibited mode - Device is prohibited from creating new MUSA contexts. MU_COMPUTEMODE_EXCLUSIVE_PROCESS: Compute-exclusive-process mode - Device can have only one context used by a single process at a time. MU_DEVICE_ATTRIBUTE_CONCURRENT_KERNELS: 1 if the device supports executing multiple kernels within the same context simultaneously, or 0 if not. It is not guaranteed that multiple kernels will be resident on the device concurrently so this feature should not be relied upon for correctness. MU_DEVICE_ATTRIBUTE_ECC_ENABLED: 1 if error correction is enabled on the device, 0 if error correction is disabled or not supported by the device MU_DEVICE_ATTRIBUTE_PCI_BUS_ID: PCI bus identifier of the device MU_DEVICE_ATTRIBUTE_PCI_DEVICE_ID: PCI device (also known as slot) identifier of the device MU_DEVICE_ATTRIBUTE_PCI_DOMAIN_ID: PCI domain identifier of the device MU_DEVICE_ATTRIBUTE_TCC_DRIVER: 1 if the device is using a TCC driver. TCC is only available on Tesla hardware running Windows Vista or later MU_DEVICE_ATTRIBUTE_MEMORY_CLOCK_RATE: Peak memory clock frequency in kilohertz MU_DEVICE_ATTRIBUTE_GLOBAL_MEMORY_BUS_WIDTH: Global memory bus width in bits MU_DEVICE_ATTRIBUTE_L2_CACHE_SIZE: Size of L2 cache in bytes. 0 if the device doesn't have L2 cache MU_DEVICE_ATTRIBUTE_MAX_THREADS_PER_MULTIPROCESSOR: Maximum resident threads per multiprocessor MU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING: 1 if the device shares a unified address space with the host, or 0 if not MU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR: Major compute capability version number MU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MINOR: Minor compute capability version number MU_DEVICE_ATTRIBUTE_GLOBAL_L1_CACHE_SUPPORTED: 1 if device supports caching globals in L1 cache, 0 if caching globals in L1 cache is not supported by the device MU_DEVICE_ATTRIBUTE_LOCAL_L1_CACHE_SUPPORTED: 1 if device supports caching locals in L1 cache, 0 if caching locals in L1 cache is not supported by the device MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_MULTIPROCESSOR: Maximum amount of shared memory available to a multiprocessor in bytes; this amount is shared by all thread blocks simultaneously resident on a multiprocessor MU_DEVICE_ATTRIBUTE_MAX_REGISTERS_PER_MULTIPROCESSOR: Maximum number of 32-bit registers available to a multiprocessor; this number is shared by all thread blocks simultaneously resident on a multiprocessor MU_DEVICE_ATTRIBUTE_MANAGED_MEMORY: 1 if device supports allocating managed memory on this system, 0 if allocating managed memory is not supported by the device on this system. MU_DEVICE_ATTRIBUTE_MULTI_GPU_BOARD: 1 if device is on a multi-GPU board, 0 if not. MU_DEVICE_ATTRIBUTE_MULTI_GPU_BOARD_GROUP_ID: Unique identifier for a group of devices associated with the same board. Devices on the same multi-GPU board will share the same identifier. MU_DEVICE_ATTRIBUTE_HOST_NATIVE_ATOMIC_SUPPORTED: 1 if Link between the device and the host supports native atomic operations. MU_DEVICE_ATTRIBUTE_SINGLE_TO_DOUBLE_PRECISION_PERF_RATIO: Ratio of single precision performance (in floating-point operations per second) to double precision performance. MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS: Device supports coherently accessing pageable memory without calling musaHostRegister on it. MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS: Device can coherently access managed memory concurrently with the CPU. MU_DEVICE_ATTRIBUTE_COMPUTE_PREEMPTION_SUPPORTED: Device supports Compute Preemption. MU_DEVICE_ATTRIBUTE_CAN_USE_HOST_POINTER_FOR_REGISTERED_MEM: Device can access host registered memory at the same virtual address as the CPU. MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_BLOCK_OPTIN: The maximum per block shared memory size supported on this device. This is the maximum value that can be opted into when using the muFuncSetAttribute() or muKernelSetAttribute() call. For more details see MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES: Device accesses pageable memory via the host's page tables. MU_DEVICE_ATTRIBUTE_DIRECT_MANAGED_MEM_ACCESS_FROM_HOST: The host can directly access managed memory on the device without migration. MU_DEVICE_ATTRIBUTE_VIRTUAL_MEMORY_MANAGEMENT_SUPPORTED: Device supports virtual memory management APIs like muMemAddressReserve, muMemCreate, muMemMap and related APIs MU_DEVICE_ATTRIBUTE_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR_SUPPORTED: Device supports exporting memory to a posix file descriptor with muMemExportToShareableHandle, if requested via muMemCreate MU_DEVICE_ATTRIBUTE_HANDLE_TYPE_WIN32_HANDLE_SUPPORTED: Device supports exporting memory to a Win32 NT handle with muMemExportToShareableHandle, if requested via muMemCreate MU_DEVICE_ATTRIBUTE_HANDLE_TYPE_WIN32_KMT_HANDLE_SUPPORTED: Device supports exporting memory to a Win32 KMT handle with muMemExportToShareableHandle, if requested via muMemCreate MU_DEVICE_ATTRIBUTE_MAX_BLOCKS_PER_MULTIPROCESSOR: Maximum number of thread blocks that can reside on a multiprocessor MU_DEVICE_ATTRIBUTE_GENERIC_COMPRESSION_SUPPORTED: Device supports compressible memory allocation via muMemCreate MU_DEVICE_ATTRIBUTE_MAX_PERSISTING_L2_CACHE_SIZE: Maximum L2 persisting lines capacity setting in bytes MU_DEVICE_ATTRIBUTE_MAX_ACCESS_POLICY_WINDOW_SIZE: Maximum value of MUaccessPolicyWindow::num_bytes MU_DEVICE_ATTRIBUTE_GPU_DIRECT_RDMA_WITH_MUSA_VMM_SUPPORTED: Device supports specifying the GPUDirect RDMA flag with muMemCreate. MU_DEVICE_ATTRIBUTE_RESERVED_SHARED_MEMORY_PER_BLOCK: Amount of shared memory per block reserved by MUSA driver in bytes MU_DEVICE_ATTRIBUTE_SPARSE_MUSA_ARRAY_SUPPORTED: Device supports sparse MUSA arrays and sparse MUSA mipmapped arrays. MU_DEVICE_ATTRIBUTE_READ_ONLY_HOST_REGISTER_SUPPORTED: Device supports using the muMemHostRegister flag MU_MEMHOSTERGISTER_READ_ONLY to register memory that must be mapped as read-only to the GPU MU_DEVICE_ATTRIBUTE_MEMORY_POOLS_SUPPORTED: Device supports using the muMemAllocAsync and muMemPool family of APIs MU_DEVICE_ATTRIBUTE_GPU_DIRECT_RDMA_SUPPORTED: Device supports GPUDirect RDMA APIs, like mthreads_p2p_get_pages (see https://docs.mthreads.com/musa/gpudirect-rdma for more information) MU_DEVICE_ATTRIBUTE_GPU_DIRECT_RDMA_FLUSH_WRITES_OPTIONS: The returned attribute shall be interpreted as a bitmask, where the individual bits are described by the MUflushGPUDirectRDMAWritesOptions enum MU_DEVICE_ATTRIBUTE_GPU_DIRECT_RDMA_WRITES_ORDERING: GPUDirect RDMA writes to the device do not need to be flushed for consumers within the scope indicated by the returned attribute. See MUGPUDirectRDMAWritesOrdering for the numerical values returned here. MU_DEVICE_ATTRIBUTE_MEMPOOL_SUPPORTED_HANDLE_TYPES: Bitmask of handle types supported with mempool based IPC MU_DEVICE_ATTRIBUTE_DEFERRED_MAPPING_MUSA_ARRAY_SUPPORTED: Device supports deferred mapping MUSA arrays and MUSA mipmapped arrays. MU_DEVICE_ATTRIBUTE_NUMA_CONFIG: NUMA configuration of a device: value is of type MUdeviceNumaConfig enum MU_DEVICE_ATTRIBUTE_NUMA_ID: NUMA node ID of the GPU memory MU_DEVICE_ATTRIBUTE_MULTICAST_SUPPORTED: Device supports switch multicast and reduction operations. MU_DEVICE_ATTRIBUTE_GPU_PCI_DEVICE_ID: The combined 16-bit PCI device ID and 16-bit PCI vendor ID. MU_DEVICE_ATTRIBUTE_GPU_PCI_SUBSYSTEM_ID: The combined 16-bit PCI subsystem ID and 16-bit PCI subsystem vendor ID. ID.

Parameters

  • pi (int *): Returned device attribute value
  • attrib (MUdevice_attribute): Device attribute to query
  • dev (MUdevice): Device handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceSetMemPool​

MUresult muDeviceSetMemPool(MUdevice dev, MUmemoryPool pool)

Description

  • Queries details about atomic operations supported between the device and host.
  • Returns in *capabilities the details about requested atomic *operations over the the link between dev and the host. The allocated size of *operations and *capabilities must be count.
  • For each MUatomicOperation in *operations, the corresponding result in *capabilities will be a bitmask indicating which of MUatomicOperationCapability the link supports natively.
  • Returns MUSA_ERROR_INVALID_DEVICE if dev is not valid.
  • Returns MUSA_ERROR_INVALID_VALUE if *capabilities or *operations is NULL, if count is 0, or if any of *operations is not valid.
  • Returns in mtSciSyncAttrList, the properties of NvSciSync that this MUSA device, dev can support. The returned mtSciSyncAttrList can be used to create an NvSciSync object that matches this device's capabilities.
  • If NvSciSyncAttrKey_RequiredPerm field in mtSciSyncAttrList is already set this API will return MUSA_ERROR_INVALID_VALUE.
  • The applications should set mtSciSyncAttrList to a valid NvSciSyncAttrList failing which this API will return MUSA_ERROR_INVALID_HANDLE.
  • The flags controls how applications intends to use the NvSciSync created from the mtSciSyncAttrList. The valid flags are: MUSA_MTSCISYNC_ATTR_SIGNAL, specifies that the applications intends to signal an NvSciSync on this MUSA device. MUSA_MTSCISYNC_ATTR_WAIT, specifies that the applications intends to wait on an NvSciSync on this MUSA device.
  • At least one of these flags must be set, failing which the API returns MUSA_ERROR_INVALID_VALUE. Both the flags are orthogonal to one another: a developer may set both these flags that allows to set both wait and signal specific attributes in the same mtSciSyncAttrList.
  • Note that this API updates the input mtSciSyncAttrList with values equivalent to the following public attribute key-values: NvSciSyncAttrKey_RequiredPerm is set to NvSciSyncAccessPerm_SignalOnly if MUSA_MTSCISYNC_ATTR_SIGNAL is set in flags. NvSciSyncAccessPerm_WaitOnly if MUSA_MTSCISYNC_ATTR_WAIT is set in flags. NvSciSyncAccessPerm_WaitSignal if both MUSA_MTSCISYNC_ATTR_WAIT and MUSA_MTSCISYNC_ATTR_SIGNAL are set in flags. NvSciSyncAttrKey_PrimitiveInfo is set to NvSciSyncAttrValPrimitiveType_SysmemSemaphore on any valid device. NvSciSyncAttrValPrimitiveType_Syncpoint if device is a Tegra device. NvSciSyncAttrValPrimitiveType_SysmemSemaphorePayload64b if device is GA10X+. NvSciSyncAttrKey_GpuId is set to the same UUID that is returned for this device from muDeviceGetUuid.
  • The memory pool must be local to the specified device. muMemAllocAsync allocates from the current mempool of the provided stream's device. By default, a device's current memory pool is its default memory pool.

Parameters

  • dev (MUdevice): Valid Musa Device to get NvSciSync attributes for.
  • pool (MUmemoryPool)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE
  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • Use muMemAllocFromPoolAsync to specify asynchronous allocations from a device different than the one the stream runs on.

See also

muDeviceGetMemPool​

MUresult muDeviceGetMemPool(MUmemoryPool *pool, MUdevice dev)

Description

  • Gets the current mempool for a device.
  • Returns the last pool provided to muDeviceSetMemPool for this device or the device's default memory pool if muDeviceSetMemPool has never been called. By default the current mempool is the default mempool for a device. Otherwise the returned pool must have been set with muDeviceSetMemPool.

Parameters

  • pool (MUmemoryPool *)
  • dev (MUdevice)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

See also

muDeviceGetDefaultMemPool​

MUresult muDeviceGetDefaultMemPool(MUmemoryPool *pool_out, MUdevice dev)

Description

  • Returns the default mempool of a device.
  • The default mempool of a device contains device memory from that device.

Parameters

  • pool_out (MUmemoryPool *)
  • dev (MUdevice)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.5 Device Management [DEPRECATED]​

muDeviceGetProperties​

MUresult muDeviceGetProperties(MUdevprop *prop, MUdevice dev)

Description

  • Returns properties for a selected device.
  • Deprecated
  • This function was deprecated as of MUSA 5.0 and replaced by muDeviceGetAttribute().
  • Returns in *prop the properties of device dev. The MUdevprop structure is defined as:
typedef struct MUdevprop_st {
  int maxThreadsPerBlock;
  int maxThreadsDim[3];
  int maxGridSize[3];
  int sharedMemPerBlock;
  int totalConstantMemory;
  int SIMDWidth;
  int memPitch;
  int regsPerBlock;
  int clockRate;
  int textureAlign;
} MUdevprop;
  • where:
  • maxThreadsPerBlock is the maximum number of threads per block; maxThreadsDim[3] is the maximum sizes of each dimension of a block; maxGridSize[3] is the maximum sizes of each dimension of a grid; sharedMemPerBlock is the total amount of shared memory available per block in bytes; totalConstantMemory is the total amount of constant memory available on the device in bytes; SIMDWidth is the warp size; memPitch is the maximum pitch allowed by the memory copy functions that involve memory regions allocated through muMemAllocPitch(); regsPerBlock is the total number of registers available per block; clockRate is the clock frequency in kilohertz; textureAlign is the alignment requirement; texture base addresses that are aligned to textureAlign bytes do not need an offset applied to texture fetches.

Parameters

  • prop (MUdevprop *): Returned properties of device
  • dev (MUdevice): Device to get properties for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceComputeCapability​

MUresult muDeviceComputeCapability(int *major, int *minor, MUdevice dev)

Description

  • Returns the compute capability of the device.
  • Deprecated
  • This function was deprecated as of MUSA 5.0 and its functionality superseded by muDeviceGetAttribute().
  • Returns in *major and *minor the major and minor revision numbers that define the compute capability of the device dev.

Parameters

  • major (int *): Major revision number
  • minor (int *): Minor revision number
  • dev (MUdevice): Device handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.6 Primary Context Management​

muDevicePrimaryCtxRetain​

MUresult muDevicePrimaryCtxRetain(MUcontext *pctx, MUdevice dev)

Description

  • Retain the primary context on the GPU.
  • Retains the primary context on the device. Once the user successfully retains the primary context, the primary context will be active and available to the user until the user releases it with muDevicePrimaryCtxRelease() or resets it with muDevicePrimaryCtxReset(). Unlike muCtxCreate() the newly retained context is not pushed onto the stack.
  • Retaining the primary context for the first time will fail with MUSA_ERROR_UNKNOWN if the compute mode of the device is MU_COMPUTEMODE_PROHIBITED. The function muDeviceGetAttribute() can be used with MU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The mthreads-smi tool can be used to set the compute mode for devices. Documentation for mthreads-smi can be obtained by passing a -h option to it.
  • Please note that the primary context always supports pinned allocations. Other flags can be specified by muDevicePrimaryCtxSetFlags().

Parameters

  • pctx (MUcontext *): Returned context handle of the new context
  • dev (MUdevice): Device for which primary context is requested

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDevicePrimaryCtxRelease​

MUresult muDevicePrimaryCtxRelease(MUdevice dev)

Description

  • Release the primary context on the GPU.
  • Releases the primary context interop on the device. A retained context should always be released once the user is done using it. The context is automatically reset once the last reference to it is released. This behavior is different when the primary context was retained by the MUSA runtime from MUSA 4.0 and earlier. In this case, the primary context remains always active.
  • Releasing a primary context that has not been previously retained will fail with MUSA_ERROR_INVALID_CONTEXT.
  • Please note that unlike muCtxDestroy() this method does not pop the context from stack in any circumstances.

Parameters

  • dev (MUdevice): Device which primary context is released

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_CONTEXT

Note

  • Additional exported symbol names in scope: muDevicePrimaryCtxRelease_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muDevicePrimaryCtxSetFlags​

MUresult muDevicePrimaryCtxSetFlags(MUdevice dev, unsigned int flags)

Description

  • Set flags for the primary context.
  • Sets the flags for the primary context on the device overwriting perviously set ones.
  • The three LSBs of the flags parameter can be used to control how the OS thread, which owns the MUSA context at the time of an API call, interacts with the OS scheduler when waiting for results from the GPU. Only one of the scheduling flags can be set when creating a context.
  • MU_CTX_SCHED_SPIN: Instruct MUSA to actively spin when waiting for results from the GPU. This can decrease latency when waiting for the GPU, but may lower the performance of CPU threads if they are performing work in parallel with the MUSA thread. MU_CTX_SCHED_YIELD: Instruct MUSA to yield its thread when waiting for results from the GPU. This can increase latency when waiting for the GPU, but can increase the performance of CPU threads performing work in parallel with the GPU. MU_CTX_SCHED_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. MU_CTX_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. Deprecated: This flag was deprecated as of MUSA 4.0 and was replaced with MU_CTX_SCHED_BLOCKING_SYNC. MU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic based on the number of active MUSA contexts in the process C and the number of logical processors in the system P. If C > P, then MUSA will yield to other OS threads when waiting for the GPU (MU_CTX_SCHED_YIELD), otherwise MUSA will not yield while waiting for results and actively spin on the processor (MU_CTX_SCHED_SPIN). Additionally, on Tegra devices, MU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may choose MU_CTX_SCHED_BLOCKING_SYNC for low-powered devices. MU_CTX_LMEM_RESIZE_TO_MAX: Instruct MUSA to not reduce local memory after resizing local memory for a kernel. This can prevent thrashing by local memory allocations when launching many kernels with high local memory usage at the cost of potentially increased memory usage. Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and cannot be disabled. MU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if this context raises an exception during execution. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. The initial settings will be taken from the global settings at the time of context creation. The other settings that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. MU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if data is written to a certain pipe that is present in the OS space. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. It is important to note that the pipe name must be set with muCoredumpSetAttributeGlobal before creating the context if this flag is used. Setting this flag implies that MU_CTX_COREDUMP_ENABLE is set. The initial settings will be taken from the global settings at the time of context creation. The other settings that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. MU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on this context will always synchronize. See further documentation in the section titled "API Synchronization behavior" to learn more about cases when synchronous memory operations can exhibit asynchronous behavior.

Parameters

  • dev (MUdevice): Device for which the primary context flags are set
  • flags (unsigned int): New flags for the device

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muDevicePrimaryCtxSetFlags_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muDevicePrimaryCtxGetState​

MUresult muDevicePrimaryCtxGetState(MUdevice dev, unsigned int *flags, int *active)

Description

  • Get the state of the primary context.
  • Returns in *flags the flags for the primary context of dev, and in *active whether it is active. See muDevicePrimaryCtxSetFlags for flag values.

Parameters

  • dev (MUdevice): Device to get primary context flags for
  • flags (unsigned int *): Pointer to store flags
  • active (int *): Pointer to store context state; 0 = inactive, 1 = active

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDevicePrimaryCtxReset​

MUresult muDevicePrimaryCtxReset(MUdevice dev)

Description

  • Destroy all allocations and reset all state on the primary context.
  • Explicitly destroys and cleans up all resources associated with the current device in the current process.
  • Note that it is responsibility of the calling function to ensure that no other module in the process is using the device any more. For that reason it is recommended to use muDevicePrimaryCtxRelease() in most cases. However it is safe for other modules to call muDevicePrimaryCtxRelease() even after resetting the device. Resetting the primary context does not release it, an application that has retained the primary context should explicitly release its usage.

Parameters

  • dev (MUdevice): Device for which primary context is destroyed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_PRIMARY_CONTEXT_ACTIVE

Note

  • Additional exported symbol names in scope: muDevicePrimaryCtxReset_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

3.7 Context Management​

muCtxCreate​

MUresult muCtxCreate(MUcontext *pctx, unsigned int flags, MUdevice dev)

Description

  • Create a MUSA context.
  • The three LSBs of the flags parameter can be used to control how the OS thread, which owns the MUSA context at the time of an API call, interacts with the OS scheduler when waiting for results from the GPU. Only one of the scheduling flags can be set when creating a context.
  • MU_CTX_SCHED_SPIN: Instruct MUSA to actively spin when waiting for results from the GPU. This can decrease latency when waiting for the GPU, but may lower the performance of CPU threads if they are performing work in parallel with the MUSA thread. MU_CTX_SCHED_YIELD: Instruct MUSA to yield its thread when waiting for results from the GPU. This can increase latency when waiting for the GPU, but can increase the performance of CPU threads performing work in parallel with the GPU. MU_CTX_SCHED_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. MU_CTX_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. Deprecated: This flag was deprecated as of MUSA 4.0 and was replaced with MU_CTX_SCHED_BLOCKING_SYNC. MU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic based on the number of active MUSA contexts in the process C and the number of logical processors in the system P. If C > P, then MUSA will yield to other OS threads when waiting for the GPU (MU_CTX_SCHED_YIELD), otherwise MUSA will not yield while waiting for results and actively spin on the processor (MU_CTX_SCHED_SPIN). Additionally, on Tegra devices, MU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may choose MU_CTX_SCHED_BLOCKING_SYNC for low-powered devices. MU_CTX_MAP_HOST: Instruct MUSA to support mapped pinned allocations. This flag must be set in order to allocate pinned host memory that is accessible to the GPU. MU_CTX_LMEM_RESIZE_TO_MAX: Instruct MUSA to not reduce local memory after resizing local memory for a kernel. This can prevent thrashing by local memory allocations when launching many kernels with high local memory usage at the cost of potentially increased memory usage. Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and cannot be disabled. Instead, the per-thread stack size can be controlled with muCtxSetLimit(). MU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if this context raises an exception during execution. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. MU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if data is written to a certain pipe that is present in the OS space. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. It is important to note that the pipe name must be set with muCoredumpSetAttributeGlobal before creating the context if this flag is used. Setting this flag implies that MU_CTX_COREDUMP_ENABLE is set. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. Setting this flag on any context creation is equivalent to setting the MU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally. MU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on this context will always synchronize. See further documentation in the section titled "API Synchronization behavior" to learn more about cases when synchronous memory operations can exhibit asynchronous behavior.
  • Context creation will fail with MUSA_ERROR_UNKNOWN if the compute mode of the device is MU_COMPUTEMODE_PROHIBITED. The function muDeviceGetAttribute() can be used with MU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The mthreads-smi tool can be used to set the compute mode for * devices. Documentation for mthreads-smi can be obtained by passing a -h option to it.

Parameters

  • pctx (MUcontext *): Returned context handle of the new context
  • flags (unsigned int): Context creation flags
  • dev (MUdevice): Device to create context on

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN

Note

  • Additional exported symbol names in scope: muCtxCreate_v2.
  • In most cases it is recommended to use muDevicePrimaryCtxRetain.
  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxDestroy​

MUresult muCtxDestroy(MUcontext ctx)

Description

  • Create a MUSA context with execution affinity.
  • Creates a new MUSA context with execution affinity and associates it with the calling thread. The paramsArray and flags parameter are described below. The context is created with a usage count of 1 and the caller of muCtxCreate() must call muCtxDestroy() when done using the context. If a context is already current to the thread, it is supplanted by the newly created context and may be restored by a subsequent call to muCtxPopCurrent().
  • The type and the amount of execution resource the context can use is limited by paramsArray and numParams. The paramsArray is an array of MUexecAffinityParam and the numParams describes the size of the array. If two MUexecAffinityParam in the array have the same type, the latter execution affinity parameter overrides the former execution affinity parameter. The supported execution affinity types are: MU_EXEC_AFFINITY_TYPE_SM_COUNT limits the portion of SMs that the context can use. The portion of SMs is specified as the number of SMs via MUexecAffinitySmCount. This limit will be internally rounded up to the next hardware-supported amount. Hence, it is imperative to query the actual execution affinity of the context via muCtxGetExecAffinity after context creation. Currently, this attribute is only supported under Volta+ MPS.
  • The three LSBs of the flags parameter can be used to control how the OS thread, which owns the MUSA context at the time of an API call, interacts with the OS scheduler when waiting for results from the GPU. Only one of the scheduling flags can be set when creating a context.
  • MU_CTX_SCHED_SPIN: Instruct MUSA to actively spin when waiting for results from the GPU. This can decrease latency when waiting for the GPU, but may lower the performance of CPU threads if they are performing work in parallel with the MUSA thread. MU_CTX_SCHED_YIELD: Instruct MUSA to yield its thread when waiting for results from the GPU. This can increase latency when waiting for the GPU, but can increase the performance of CPU threads performing work in parallel with the GPU. MU_CTX_SCHED_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. MU_CTX_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. Deprecated: This flag was deprecated as of MUSA 4.0 and was replaced with MU_CTX_SCHED_BLOCKING_SYNC. MU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic based on the number of active MUSA contexts in the process C and the number of logical processors in the system P. If C > P, then MUSA will yield to other OS threads when waiting for the GPU (MU_CTX_SCHED_YIELD), otherwise MUSA will not yield while waiting for results and actively spin on the processor (MU_CTX_SCHED_SPIN). Additionally, on Tegra devices, MU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may choose MU_CTX_SCHED_BLOCKING_SYNC for low-powered devices. MU_CTX_MAP_HOST: Instruct MUSA to support mapped pinned allocations. This flag must be set in order to allocate pinned host memory that is accessible to the GPU. MU_CTX_LMEM_RESIZE_TO_MAX: Instruct MUSA to not reduce local memory after resizing local memory for a kernel. This can prevent thrashing by local memory allocations when launching many kernels with high local memory usage at the cost of potentially increased memory usage. Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and cannot be disabled. Instead, the per-thread stack size can be controlled with muCtxSetLimit(). MU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if this context raises an exception during execution. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. MU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if data is written to a certain pipe that is present in the OS space. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. It is important to note that the pipe name must be set with muCoredumpSetAttributeGlobal before creating the context if this flag is used. Setting this flag implies that MU_CTX_COREDUMP_ENABLE is set. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. Setting this flag on any context creation is equivalent to setting the MU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally.
  • Context creation will fail with MUSA_ERROR_UNKNOWN if the compute mode of the device is MU_COMPUTEMODE_PROHIBITED. The function muDeviceGetAttribute() can be used with MU_DEVICE_ATTRIBUTE_COMPUTE_MODE to determine the compute mode of the device. The mthreads-smi tool can be used to set the compute mode for * devices. Documentation for mthreads-smi can be obtained by passing a -h option to it.
  • Creates a new MUSA context and associates it with the calling thread. The flags parameter is described below. The context is created with a usage count of 1 and the caller of muCtxCreate() must call muCtxDestroy() when done using the context. If a context is already current to the thread, it is supplanted by the newly created context and may be restored by a subsequent call to muCtxPopCurrent().
  • MUSA context can be created with execution affinity. The type and the amount of execution resource the context can use is limited by paramsArray and numExecAffinityParams in execAffinity. The paramsArray is an array of MUexecAffinityParam and the numExecAffinityParams describes the size of the paramsArray. If two MUexecAffinityParam in the array have the same type, the latter execution affinity parameter overrides the former execution affinity parameter. The supported execution affinity types are: MU_EXEC_AFFINITY_TYPE_SM_COUNT limits the portion of SMs that the context can use. The portion of SMs is specified as the number of SMs via MUexecAffinitySmCount. This limit will be internally rounded up to the next hardware-supported amount. Hence, it is imperative to query the actual execution affinity of the context via muCtxGetExecAffinity after context creation. Currently, this attribute is only supported under Volta+ MPS.
  • MUSA context can be created in CIG(MUSA in Graphics) mode by setting cigParams. Data from graphics client is shared with MUSA via the sharedData in cigParams. Support for D3D12 graphics client can be determined using muDeviceGetAttribute() with MU_DEVICE_ATTRIBUTE_D3D12_CIG_SUPPORTED. sharedData is a ID3D12CommandQueue handle. Either execAffinityParams or cigParams can be set to a non-null value. Setting both to a non-null value will result in an undefined behavior.
  • MU_CTX_SCHED_SPIN: Instruct MUSA to actively spin when waiting for results from the GPU. This can decrease latency when waiting for the GPU, but may lower the performance of CPU threads if they are performing work in parallel with the MUSA thread. MU_CTX_SCHED_YIELD: Instruct MUSA to yield its thread when waiting for results from the GPU. This can increase latency when waiting for the GPU, but can increase the performance of CPU threads performing work in parallel with the GPU. MU_CTX_SCHED_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. MU_CTX_BLOCKING_SYNC: Instruct MUSA to block the CPU thread on a synchronization primitive when waiting for the GPU to finish work. Deprecated: This flag was deprecated as of MUSA 4.0 and was replaced with MU_CTX_SCHED_BLOCKING_SYNC. MU_CTX_SCHED_AUTO: The default value if the flags parameter is zero, uses a heuristic based on the number of active MUSA contexts in the process C and the number of logical processors in the system P. If C > P, then MUSA will yield to other OS threads when waiting for the GPU (MU_CTX_SCHED_YIELD), otherwise MUSA will not yield while waiting for results and actively spin on the processor (MU_CTX_SCHED_SPIN). Additionally, on Tegra devices, MU_CTX_SCHED_AUTO uses a heuristic based on the power profile of the platform and may choose MU_CTX_SCHED_BLOCKING_SYNC for low-powered devices. MU_CTX_MAP_HOST: Instruct MUSA to support mapped pinned allocations. This flag must be set in order to allocate pinned host memory that is accessible to the GPU. MU_CTX_LMEM_RESIZE_TO_MAX: Instruct MUSA to not reduce local memory after resizing local memory for a kernel. This can prevent thrashing by local memory allocations when launching many kernels with high local memory usage at the cost of potentially increased memory usage. Deprecated: This flag is deprecated and the behavior enabled by this flag is now the default and cannot be disabled. Instead, the per-thread stack size can be controlled with muCtxSetLimit(). MU_CTX_COREDUMP_ENABLE: If GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if this context raises an exception during execution. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. This flag is not supported when MUSA context is created in CIG(MUSA in Graphics) mode. MU_CTX_USER_COREDUMP_ENABLE: If user-triggered GPU coredumps have not been enabled globally with muCoredumpSetAttributeGlobal or environment variables, this flag can be set during context creation to instruct MUSA to create a coredump if data is written to a certain pipe that is present in the OS space. These environment variables are described in the MUSA-GDB user guide under the "GPU core dump support" section. It is important to note that the pipe name must be set with muCoredumpSetAttributeGlobal before creating the context if this flag is used. Setting this flag implies that MU_CTX_COREDUMP_ENABLE is set. The initial attributes will be taken from the global attributes at the time of context creation. The other attributes that control coredump output can be modified by calling muCoredumpSetAttribute from the created context after it becomes current. Setting this flag on any context creation is equivalent to setting the MU_COREDUMP_ENABLE_USER_TRIGGER attribute to true globally. This flag is not supported when MUSA context is created in CIG(MUSA in Graphics) mode. MU_CTX_SYNC_MEMOPS: Ensures that synchronous memory operations initiated on this context will always synchronize. See further documentation in the section titled "API Synchronization behavior" to learn more about cases when synchronous memory operations can exhibit asynchronous behavior.
  • Context creation will fail with MUSA_ERROR_INVALID_VALUE if invalid parameter was passed by client to create the MUSA context.
  • Destroys the MUSA context specified by ctx. The context ctx will be destroyed regardless of how many threads it is current to. It is the responsibility of the calling function to ensure that no API call issues using ctx while muCtxDestroy() is executing.
  • Destroys and cleans up all resources associated with the context. It is the caller's responsibility to ensure that the context or its resources are not accessed or passed in subsequent API calls and doing so will result in undefined behavior. These resources include MUSA types MUmodule, MUfunction, MUstream, MUevent, MUarray, MUmipmappedArray, MUtexObject, MUsurfObject, MUtexref, MUsurfref, MUgraphicsResource, MUlinkState, MUexternalMemory and MUexternalSemaphore. These resources also include memory allocations by muMemAlloc(), muMemAllocHost(), muMemAllocManaged() and muMemAllocPitch().
  • If ctx is current to the calling thread then ctx will also be popped from the current thread's context stack (as though muCtxPopCurrent() were called). If ctx is current to other threads, then ctx will remain current to those threads, and attempting to access ctx from those threads will result in the error MUSA_ERROR_CONTEXT_IS_DESTROYED.

Parameters

  • ctx (MUcontext): Context to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNSUPPORTED_EXEC_AFFINITY, MUSA_ERROR_UNKNOWN
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muCtxDestroy_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • muCtxDestroy() will not destroy memory allocations by muMemCreate(), muMemAllocAsync() and muMemAllocFromPoolAsync(). These memory allocations are not associated with any MUSA context and need to be destroyed explicitly.

See also

muCtxPushCurrent​

MUresult muCtxPushCurrent(MUcontext ctx)

Description

  • Pushes a context on the current CPU thread.
  • Pushes the given context ctx onto the CPU thread's stack of current contexts. The specified context becomes the CPU thread's current context, so all MUSA functions that operate on the current context are affected.
  • The previous current context may be made current again by calling muCtxDestroy() or muCtxPopCurrent().

Parameters

  • ctx (MUcontext): Context to push

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muCtxPushCurrent_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxPopCurrent​

MUresult muCtxPopCurrent(MUcontext *pctx)

Description

  • Pops the current MUSA context from the current CPU thread.
  • Pops the current MUSA context from the CPU thread and passes back the old context handle in *pctx. That context may then be made current to a different CPU thread by calling muCtxPushCurrent().
  • If a context was current to the CPU thread before muCtxCreate() or muCtxPushCurrent() was called, this function makes that context current to the CPU thread again.

Parameters

  • pctx (MUcontext *): Returned popped context handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • Additional exported symbol names in scope: muCtxPopCurrent_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSetCurrent​

MUresult muCtxSetCurrent(MUcontext ctx)

Description

  • Binds the specified MUSA context to the calling CPU thread.
  • Binds the specified MUSA context to the calling CPU thread. If ctx is NULL then the MUSA context previously bound to the calling CPU thread is unbound and MUSA_SUCCESS is returned.
  • If there exists a MUSA context stack on the calling CPU thread, this will replace the top of that stack with ctx. If ctx is NULL then this will be equivalent to popping the top of the calling CPU thread's MUSA context stack (or a no-op if the calling CPU thread's MUSA context stack is empty).

Parameters

  • ctx (MUcontext): Context to bind to the calling CPU thread

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetCurrent​

MUresult muCtxGetCurrent(MUcontext *pctx)

Description

  • Returns the MUSA context bound to the calling CPU thread.
  • Returns in *pctx the MUSA context bound to the calling CPU thread. If no context is bound to the calling CPU thread then *pctx is set to NULL and MUSA_SUCCESS is returned.

Parameters

  • pctx (MUcontext *): Returned context handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetDevice​

MUresult muCtxGetDevice(MUdevice *device)

Description

  • Returns the device handle for the current context.
  • Returns in *device the handle of the current context's device.

Parameters

  • device (MUdevice *): Returned device handle for the current context

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetFlags​

MUresult muCtxGetFlags(unsigned int *flags)

Description

  • Returns the device handle for the specified context.
  • Returns in *device the handle of the specified context's device. If the specified context is NULL, the API will return the current context's device.
  • Returns in *flags the flags of the current context. See muCtxCreate for flag values.

Parameters

  • flags (unsigned int *): Pointer to store flags of current context

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSetFlags​

MUresult muCtxSetFlags(unsigned int flags)

Description

  • Sets the flags for the current context.
  • Sets the flags for the current context overwriting previously set ones. See muDevicePrimaryCtxSetFlags for flag values.

Parameters

  • flags (unsigned int): Flags to set on the current context

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetId​

MUresult muCtxGetId(MUcontext ctx, unsigned long long *ctxId)

Description

  • Returns the unique Id associated with the context supplied.
  • Returns in ctxId the unique Id which is associated with a given context. The Id is unique for the life of the program for this instance of MUSA. If context is supplied as NULL and there is one current, the Id of the current context is returned.

Parameters

  • ctx (MUcontext): Context for which to obtain the Id
  • ctxId (unsigned long long *): Pointer to store the Id of the context

Returns

  • MUSA_SUCCESS, MUSA_ERROR_CONTEXT_IS_DESTROYED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSynchronize​

MUresult muCtxSynchronize(void)

Description

  • Block for the current context's tasks to complete.
  • Blocks until the current context has completed all preceding requested tasks. If the current context is the primary context, green contexts that have been created will also be synchronized. muCtxSynchronize() returns an error if one of the preceding tasks failed. If the context was created with the MU_CTX_SCHED_BLOCKING_SYNC flag, the CPU thread will block until the GPU context has finished its work.

Parameters

  • (unnamed) (void)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSetLimit​

MUresult muCtxSetLimit(MUlimit limit, size_t value)

Description

  • Block for the specified context's tasks to complete.
  • Blocks until the specified context has completed all preceding requested tasks. If the specified context is the primary context, green contexts that have been created will also be synchronized. The API returns an error if one of the preceding tasks failed.
  • If the context was created with the MU_CTX_SCHED_BLOCKING_SYNC flag, the CPU thread will block until the GPU context has finished its work.
  • If the specified context is NULL, the API will operate on the current context.
  • Setting limit to value is a request by the application to update the current limit maintained by the context. The driver is free to modify the requested value to meet h/w requirements (this could be clamping to minimum or maximum values, rounding up to nearest element size, etc). The application can use muCtxGetLimit() to find out exactly what the limit has been set to.
  • Setting each MUlimit has its own specific restrictions, so each is discussed here.
  • MU_LIMIT_STACK_SIZE controls the stack size in bytes of each GPU thread. The driver automatically increases the per-thread stack size for each kernel launch as needed. This size isn't reset back to the original value after each launch. Setting this value will take effect immediately, and if necessary, the device will block until all preceding requested tasks are complete. MU_LIMIT_PRINTF_FIFO_SIZE controls the size in bytes of the FIFO used by the printf() device system call. Setting MU_LIMIT_PRINTF_FIFO_SIZE must be performed before launching any kernel that uses the printf() device system call, otherwise MUSA_ERROR_INVALID_VALUE will be returned. MU_LIMIT_MALLOC_HEAP_SIZE controls the size in bytes of the heap used by the malloc() and free() device system calls. Setting MU_LIMIT_MALLOC_HEAP_SIZE must be performed before launching any kernel that uses the malloc() or free() device system calls, otherwise MUSA_ERROR_INVALID_VALUE will be returned. MU_LIMIT_DEV_RUNTIME_SYNC_DEPTH controls the maximum nesting depth of a grid at which a thread can safely call musaDeviceSynchronize(). Setting this limit must be performed before any launch of a kernel that uses the device runtime and calls musaDeviceSynchronize() above the default sync depth, two levels of grids. Calls to musaDeviceSynchronize() will fail with error code musaErrorSyncDepthExceeded if the limitation is violated. This limit can be set smaller than the default or up the maximum launch depth of 24. When setting this limit, keep in mind that additional levels of sync depth require the driver to reserve large amounts of device memory which can no longer be used for user allocations. If these reservations of device memory fail, muCtxSetLimit() will return MUSA_ERROR_OUT_OF_MEMORY, and the limit can be reset to a lower value. This limit is only applicable to devices of compute capability < 9.0. Attempting to set this limit on devices of other compute capability versions will result in the error MUSA_ERROR_UNSUPPORTED_LIMIT being returned. MU_LIMIT_DEV_RUNTIME_PENDING_LAUNCH_COUNT controls the maximum number of outstanding device runtime launches that can be made from the current context. A grid is outstanding from the point of launch up until the grid is known to have been completed. Device runtime launches which violate this limitation fail and return musaErrorLaunchPendingCountExceeded when musaGetLastError() is called after launch. If more pending launches than the default (2048 launches) are needed for a module using the device runtime, this limit can be increased. Keep in mind that being able to sustain additional pending launches will require the driver to reserve larger amounts of device memory upfront which can no longer be used for allocations. If these reservations fail, muCtxSetLimit() will return MUSA_ERROR_OUT_OF_MEMORY, and the limit can be reset to a lower value. This limit is only applicable to devices of compute capability 3.5 and higher. Attempting to set this limit on devices of compute capability less than 3.5 will result in the error MUSA_ERROR_UNSUPPORTED_LIMIT being returned. MU_LIMIT_MAX_L2_FETCH_GRANULARITY controls the L2 cache fetch granularity. Values can range from 0B to 128B. This is purely a performance hint and it can be ignored or clamped depending on the platform. MU_LIMIT_PERSISTING_L2_CACHE_SIZE controls size in bytes available for persisting L2 cache. This is purely a performance hint and it can be ignored or clamped depending on the platform.

Parameters

  • limit (MUlimit): Limit to set
  • value (size_t): Size of limit

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED
  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNSUPPORTED_LIMIT, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetLimit​

MUresult muCtxGetLimit(size_t *pvalue, MUlimit limit)

Description

  • Returns resource limits.
  • Returns in *pvalue the current size of limit. The supported MUlimit values are: MU_LIMIT_STACK_SIZE: stack size in bytes of each GPU thread. MU_LIMIT_PRINTF_FIFO_SIZE: size in bytes of the FIFO used by the printf() device system call. MU_LIMIT_MALLOC_HEAP_SIZE: size in bytes of the heap used by the malloc() and free() device system calls. MU_LIMIT_DEV_RUNTIME_SYNC_DEPTH: maximum grid depth at which a thread can issue the device runtime call musaDeviceSynchronize() to wait on child grid launches to complete. MU_LIMIT_DEV_RUNTIME_PENDING_LAUNCH_COUNT: maximum number of outstanding device runtime launches that can be made from this context. MU_LIMIT_MAX_L2_FETCH_GRANULARITY: L2 cache fetch granularity. MU_LIMIT_PERSISTING_L2_CACHE_SIZE: Persisting L2 cache size in bytes

Parameters

  • pvalue (size_t *): Returned size of limit
  • limit (MUlimit): Limit to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNSUPPORTED_LIMIT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetCacheConfig​

MUresult muCtxGetCacheConfig(MUfunc_cache *pconfig)

Description

  • Returns the preferred cache configuration for the current context.
  • On devices where the L1 cache and shared memory use the same hardware resources, this function returns through pconfig the preferred cache configuration for the current context. This is only a preference. The driver will use the requested configuration if possible, but it is free to choose a different configuration if required to execute functions.
  • This will return a pconfig of MU_FUNC_CACHE_PREFER_NONE on devices where the size of the L1 cache and shared memory are fixed.
  • The supported cache configurations are: MU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default) MU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache MU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory MU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory

Parameters

  • pconfig (MUfunc_cache *): Returned cache configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSetCacheConfig​

MUresult muCtxSetCacheConfig(MUfunc_cache config)

Description

  • Sets the preferred cache configuration for the current context.
  • On devices where the L1 cache and shared memory use the same hardware resources, this sets through config the preferred cache configuration for the current context. This is only a preference. The driver will use the requested configuration if possible, but it is free to choose a different configuration if required to execute the function. Any function preference set via muFuncSetCacheConfig() or muKernelSetCacheConfig() will be preferred over this context-wide setting. Setting the context-wide cache configuration to MU_FUNC_CACHE_PREFER_NONE will cause subsequent kernel launches to prefer to not change the cache configuration unless required to launch the kernel.
  • This setting does nothing on devices where the size of the L1 cache and shared memory are fixed.
  • Launching a kernel with a different preference than the most recent preference setting may insert a device-side synchronization point.
  • The supported cache configurations are: MU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default) MU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache MU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory MU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory

Parameters

  • config (MUfunc_cache): Requested cache configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetApiVersion​

MUresult muCtxGetApiVersion(MUcontext ctx, unsigned int *version)

Description

  • Gets the context's API version.
  • Returns a version number in version corresponding to the capabilities of the context (e.g. 3010 or 3020), which library developers can use to direct callers to a specific API version. If ctx is NULL, returns the API version used to create the currently bound context.
  • Note that new API versions are only introduced when context capabilities are changed that break binary compatibility, so the API version and driver version may be different. For example, it is valid for the API version to be 3020 while the driver version is 4020.

Parameters

  • ctx (MUcontext): Context to check
  • version (unsigned int *): Pointer to version

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetStreamPriorityRange​

MUresult muCtxGetStreamPriorityRange(int *leastPriority, int *greatestPriority)

Description

  • Returns numerical values that correspond to the least and greatest stream priorities.
  • Returns in *leastPriority and *greatestPriority the numerical values that correspond to the least and greatest stream priorities respectively. Stream priorities follow a convention where lower numbers imply greater priorities. The range of meaningful stream priorities is given by [*greatestPriority, *leastPriority]. If the user attempts to create a stream with a priority value that is outside the meaningful range as specified by this API, the priority is automatically clamped down or up to either *leastPriority or *greatestPriority respectively. See muStreamCreateWithPriority for details on creating a priority stream. A NULL may be passed in for *leastPriority or *greatestPriority if the value is not desired.
  • This function will return '0' in both *leastPriority and *greatestPriority if the current context's device does not support stream priorities (see muDeviceGetAttribute).

Parameters

  • leastPriority (int *): Pointer to an int in which the numerical value for least stream priority is returned
  • greatestPriority (int *): Pointer to an int in which the numerical value for greatest stream priority is returned

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxResetPersistingL2Cache​

MUresult muCtxResetPersistingL2Cache(void)

Description

  • Resets all persisting lines in cache to normal status.
  • muCtxResetPersistingL2Cache Resets all persisting lines in cache to normal status. Takes effect on function return.

Parameters

  • (unnamed) (void)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muCtxRecordEvent​

MUresult muCtxRecordEvent(MUcontext hCtx, MUevent hEvent)

Description

  • Returns the execution affinity setting for the current context.
  • Returns in *pExecAffinity the current value of type. The supported MUexecAffinityType values are: MU_EXEC_AFFINITY_TYPE_SM_COUNT: number of SMs the context is limited to use.
  • Captures in hEvent all the activities of the context hCtx at the time of this call. hEvent and hCtx must be from the same MUSA context, otherwise MUSA_ERROR_INVALID_HANDLE will be returned. Calls such as muEventQuery() or muCtxWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hCtx after this call do not modify hEvent. If the context passed to hCtx is the primary context, hEvent will capture all the activities of the primary context and its green contexts. If the context passed to hCtx is a context converted from green context via muCtxFromGreenCtx(), hEvent will capture only the activities of the green context.

Parameters

  • hCtx (MUcontext): Context to record event for
  • hEvent (MUevent): Event to record

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNSUPPORTED_EXEC_AFFINITY
  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.
  • The API will return MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED if the specified context hCtx has a stream in the capture mode. In such a case, the call will invalidate all the conflicting captures.

See also

muCtxWaitEvent​

MUresult muCtxWaitEvent(MUcontext hCtx, MUevent hEvent)

Description

  • Make a context wait on an event.
  • Makes all future work submitted to context hCtx wait for all work captured in hEvent. The synchronization will be performed on the device and will not block the calling CPU thread. See muCtxRecordEvent() for details on what is captured by an event. If the context passed to hCtx is the primary context, the primary context and its green contexts will wait for hEvent. If the context passed to hCtx is a context converted from green context via muCtxFromGreenCtx(), the green context will wait for hEvent.

Parameters

  • hCtx (MUcontext): Context to wait
  • hEvent (MUevent): Event to wait on

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED

Note

  • hEvent may be from a different context or device than hCtx.
  • The API will return MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED and invalidate the capture if the specified event hEvent is part of an ongoing capture sequence or if the specified context hCtx has a stream in the capture mode.

See also

3.8 Context Management [DEPRECATED]​

muCtxAttach​

MUresult muCtxAttach(MUcontext *pctx, unsigned int flags)

Description

  • Increment a context's usage-count.
  • Deprecated
  • Note that this function is deprecated and should not be used.
  • Increments the usage count of the context and passes back a context handle in *pctx that must be passed to muCtxDetach() when the application is done with the context. muCtxAttach() fails if there is no context current to the thread.
  • Currently, the flags parameter must be 0.

Parameters

  • pctx (MUcontext *): Returned context handle of the current context
  • flags (unsigned int): Context attach flags (must be 0)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxDetach​

MUresult muCtxDetach(MUcontext ctx)

Description

  • Decrement a context's usage-count.
  • Deprecated
  • Note that this function is deprecated and should not be used.
  • Decrements the usage count of the context ctx, and destroys the context if the usage count goes to 0. The context must be a handle that was passed back by muCtxCreate() or muCtxAttach(), and must be current to the calling thread.

Parameters

  • ctx (MUcontext): Context to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxGetSharedMemConfig​

MUresult muCtxGetSharedMemConfig(MUsharedconfig *pConfig)

Description

  • Returns the current shared memory configuration for the current context.
  • Deprecated
  • This function will return in pConfig the current size of shared memory banks in the current context. On devices with configurable shared memory banks, muCtxSetSharedMemConfig can be used to change this setting, so that all subsequent kernel launches will by default use the new bank size. When muCtxGetSharedMemConfig is called on devices without configurable shared memory, it will return the fixed bank size of the hardware.
  • The returned bank configurations can be either: MU_SHARED_MEM_CONFIG_FOUR_BYTE_BANK_SIZE: shared memory bank width is four bytes. MU_SHARED_MEM_CONFIG_EIGHT_BYTE_BANK_SIZE: shared memory bank width will eight bytes.

Parameters

  • pConfig (MUsharedconfig *): returned shared memory configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxSetSharedMemConfig​

MUresult muCtxSetSharedMemConfig(MUsharedconfig config)

Description

  • Sets the shared memory configuration for the current context.
  • Deprecated
  • On devices with configurable shared memory banks, this function will set the context's shared memory bank size which is used for subsequent kernel launches.
  • Changed the shared memory configuration between launches may insert a device side synchronization point between those launches.
  • Changing the shared memory bank size will not increase shared memory usage or affect occupancy of kernels, but may have major effects on performance. Larger bank sizes will allow for greater potential bandwidth to shared memory, but will change what kinds of accesses to shared memory will result in bank conflicts.
  • This function will do nothing on devices with fixed shared memory bank size.
  • The supported bank configurations are: MU_SHARED_MEM_CONFIG_DEFAULT_BANK_SIZE: set bank width to the default initial setting (currently, four bytes). MU_SHARED_MEM_CONFIG_FOUR_BYTE_BANK_SIZE: set shared memory bank width to be natively four bytes. MU_SHARED_MEM_CONFIG_EIGHT_BYTE_BANK_SIZE: set shared memory bank width to be natively eight bytes.

Parameters

  • config (MUsharedconfig): requested shared memory configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.9 Module Management​

muModuleLoad​

MUresult muModuleLoad(MUmodule *module, const char *fname)

Description

  • Loads a compute module.
  • Takes a filename fname and loads the corresponding module module into the current context. The MUSA driver API does not attempt to lazily allocate the resources needed by a module; if the memory for functions and data (constant and global) needed by the module cannot be allocated, muModuleLoad() fails. The file should be a mubin file as output by nvcc, or a PTX file either as output by nvcc or handwritten, or a fatbin file as output by nvcc from toolchain 4.0 or later.

Parameters

  • module (MUmodule *): Returned module
  • fname (const char *): Filename of module to load

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_FILE_NOT_FOUND, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleLoadData​

MUresult muModuleLoadData(MUmodule *module, const void *image)

Description

  • Load a module's data.
  • Takes a pointer image and loads the corresponding module module into the current context. The image may be a mubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by nvcc or hand-written.

Parameters

  • module (MUmodule *): Returned module
  • image (const void *): Module data to load

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleLoadDataEx​

MUresult muModuleLoadDataEx(MUmodule *module, const void *image, unsigned int numOptions, MUjit_option *options, void **optionValues)

Description

  • Load a module's data with options.
  • Takes a pointer image and loads the corresponding module module into the current context. The image may be a mubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by nvcc or hand-written.

Parameters

  • module (MUmodule *): Returned module
  • image (const void *): Module data to load
  • numOptions (unsigned int): Number of options
  • options (MUjit_option *): Options for JIT
  • optionValues (void **): Option values for JIT

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleLoadFatBinary​

MUresult muModuleLoadFatBinary(MUmodule *module, const void *fatMubin)

Description

  • Load a module's data.
  • Takes a pointer fatCubin and loads the corresponding module module into the current context. The pointer represents a fat binary object, which is a collection of different mubin and/or PTX files, all representing the same device code, but compiled and optimized for different architectures.
  • Prior to MUSA 4.0, there was no documented API for constructing and using fat binary objects by programmers. Starting with MUSA 4.0, fat binary objects can be constructed by providing the -fatbin option to nvcc. More information can be found in the nvcc document.

Parameters

  • module (MUmodule *): Returned module
  • fatMubin (const void *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleUnload​

MUresult muModuleUnload(MUmodule hmod)

Description

  • Unloads a module.
  • Unloads a module hmod from the current context. Attempting to unload a module which was obtained from the Library Management API such as muLibraryGetModule will return MUSA_ERROR_NOT_PERMITTED.

Parameters

  • hmod (MUmodule): Module to unload

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_PERMITTED

Note

  • This function may also return error codes from previous, asynchronous launches.
  • Destroying the target object while work is still pending results in undefined behavior.

See also

muModuleGetLoadingMode​

MUresult muModuleGetLoadingMode(MUmoduleLoadingMode *mode)

Description

  • Query lazy loading mode.
  • Returns lazy loading mode Module loading mode is controlled by MUSA_MODULE_LOADING env variable

Parameters

  • mode (MUmoduleLoadingMode *): Returns the lazy loading mode

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleGetFunction​

MUresult muModuleGetFunction(MUfunction *hfunc, MUmodule hmod, const char *name)

Description

  • Returns a function handle.
  • Returns in *hfunc the handle of the function of name name located in module hmod. If no function of that name exists, muModuleGetFunction() returns MUSA_ERROR_NOT_FOUND.

Parameters

  • hfunc (MUfunction *): Returned function handle
  • hmod (MUmodule): Module to retrieve function from
  • name (const char *): Name of function to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleGetFunctionCount​

MUresult muModuleGetFunctionCount(unsigned int *count, MUmodule mod)

Description

  • Returns the number of functions within a module.
  • Returns in count the number of functions in mod.

Parameters

  • count (unsigned int *): Number of functions found within the module
  • mod (MUmodule): Module to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

muModuleEnumerateFunctions​

MUresult muModuleEnumerateFunctions(MUfunction *functions, unsigned int numFunctions, MUmodule mod)

Description

  • Returns the function handles within a module.
  • Returns in functions a maximum number of numFunctions function handles within mod. When function loading mode is set to LAZY the function retrieved may be partially loaded. The loading state of a function can be queried using muFunctionIsLoaded. MUSA APIs may load the function automatically when called with partially loaded function handle which may incur additional latency. Alternatively, muFunctionLoad can be used to explicitly load a function. The returned function handles become invalid when the module is unloaded.

Parameters

  • functions (MUfunction *): Buffer where the function handles are returned to
  • numFunctions (unsigned int): Maximum number of function handles may be returned to the buffer
  • mod (MUmodule): Module to query from

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muModuleGetGlobal​

MUresult muModuleGetGlobal(MUdeviceptr *dptr, size_t *bytes, MUmodule hmod, const char *name)

Description

  • Returns a global pointer from a module.
  • Returns in *dptr and *bytes the base pointer and size of the global of name name located in module hmod. If no variable of that name exists, muModuleGetGlobal() returns MUSA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can be NULL in which case it is ignored.

Parameters

  • dptr (MUdeviceptr *): Returned global device pointer
  • bytes (size_t *): Returned global size in bytes
  • hmod (MUmodule): Module to retrieve global from
  • name (const char *): Name of global to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_FOUND

Note

  • Additional exported symbol names in scope: muModuleGetGlobal_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

3.10 Module Management [DEPRECATED]​

muModuleGetTexRef​

MUresult muModuleGetTexRef(MUtexref *pTexRef, MUmodule hmod, const char *name)

Description

  • Returns a handle to a texture reference.
  • Deprecated
  • Returns in *pTexRef the handle of the texture reference of name name in the module hmod. If no texture reference of that name exists, muModuleGetTexRef() returns MUSA_ERROR_NOT_FOUND. This texture reference handle should not be destroyed, since it will be destroyed when the module is unloaded.

Parameters

  • pTexRef (MUtexref *): Returned texture reference
  • hmod (MUmodule): Module to retrieve texture reference from
  • name (const char *): Name of texture reference to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muModuleGetSurfRef​

MUresult muModuleGetSurfRef(MUsurfref *pSurfRef, MUmodule hmod, const char *name)

Description

  • Returns a handle to a surface reference.
  • Deprecated
  • Returns in *pSurfRef the handle of the surface reference of name name in the module hmod. If no surface reference of that name exists, muModuleGetSurfRef() returns MUSA_ERROR_NOT_FOUND.

Parameters

  • pSurfRef (MUsurfref *): Returned surface reference
  • hmod (MUmodule): Module to retrieve surface reference from
  • name (const char *): Name of surface reference to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.11 Library Management​

muLibraryLoadData​

MUresult muLibraryLoadData(MUlibrary *library, const void *code, MUjit_option *jitOptions, void **jitOptionsValues, unsigned int numJitOptions, MUlibraryOption *libraryOptions, void **libraryOptionValues, unsigned int numLibraryOptions)

Description

  • Load a library with specified code and options.
  • Takes a pointer code and loads the corresponding library library based on the application defined library loading mode: If module loading is set to EAGER, via the environment variables described in "Module loading", library is loaded eagerly into all contexts at the time of the call and future contexts at the time of creation until the library is unloaded with muLibraryUnload(). If the environment variables are set to LAZY, library is not immediately loaded onto all existent contexts and will only be loaded when a function is needed for that context, such as a kernel launch.
  • These environment variables are described in the MUSA programming guide under the "MUSA environment variables" section.
  • The code may be a mubin or fatbin as output by nvcc, or a NULL-terminated PTX, either as output by nvcc or hand-written. A fatbin should also contain relocatable code when doing separate compilation.
  • Options are passed as an array via jitOptions and any corresponding parameters are passed in jitOptionsValues. The number of total JIT options is supplied via numJitOptions. Any outputs will be returned via jitOptionsValues.
  • Library load options are passed as an array via libraryOptions and any corresponding parameters are passed in libraryOptionValues. The number of total library load options is supplied via numLibraryOptions.

Parameters

  • library (MUlibrary *): Returned library
  • code (const void *): Code to load
  • jitOptions (MUjit_option *): Options for JIT
  • jitOptionsValues (void **): Option values for JIT
  • numJitOptions (unsigned int): Number of options
  • libraryOptions (MUlibraryOption *): Options for loading
  • libraryOptionValues (void **): Option values for loading
  • numLibraryOptions (unsigned int): Number of options for loading

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND, MUSA_ERROR_NOT_SUPPORTED

Note

  • If the library contains managed variables and no device in the system supports managed variables this call is expected to return MUSA_ERROR_NOT_SUPPORTED

See also

muLibraryLoadFromFile​

MUresult muLibraryLoadFromFile(MUlibrary *library, const char *fileName, MUjit_option *jitOptions, void **jitOptionsValues, unsigned int numJitOptions, MUlibraryOption *libraryOptions, void **libraryOptionValues, unsigned int numLibraryOptions)

Description

  • Load a library with specified file and options.
  • Takes a pointer code and loads the corresponding library library based on the application defined library loading mode: If module loading is set to EAGER, via the environment variables described in "Module loading", library is loaded eagerly into all contexts at the time of the call and future contexts at the time of creation until the library is unloaded with muLibraryUnload(). If the environment variables are set to LAZY, library is not immediately loaded onto all existent contexts and will only be loaded when a function is needed for that context, such as a kernel launch.
  • These environment variables are described in the MUSA programming guide under the "MUSA environment variables" section.
  • The file should be a mubin file as output by nvcc, or a PTX file either as output by nvcc or handwritten, or a fatbin file as output by nvcc. A fatbin should also contain relocatable code when doing separate compilation.
  • Options are passed as an array via jitOptions and any corresponding parameters are passed in jitOptionsValues. The number of total options is supplied via numJitOptions. Any outputs will be returned via jitOptionsValues.
  • Library load options are passed as an array via libraryOptions and any corresponding parameters are passed in libraryOptionValues. The number of total library load options is supplied via numLibraryOptions.

Parameters

  • library (MUlibrary *): Returned library
  • fileName (const char *): File to load from
  • jitOptions (MUjit_option *): Options for JIT
  • jitOptionsValues (void **): Option values for JIT
  • numJitOptions (unsigned int): Number of options
  • libraryOptions (MUlibraryOption *): Options for loading
  • libraryOptionValues (void **): Option values for loading
  • numLibraryOptions (unsigned int): Number of options for loading

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_PTX, MUSA_ERROR_UNSUPPORTED_PTX_VERSION, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NO_BINARY_FOR_GPU, MUSA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_JIT_COMPILER_NOT_FOUND, MUSA_ERROR_NOT_SUPPORTED

Note

  • If the library contains managed variables and no device in the system supports managed variables this call is expected to return MUSA_ERROR_NOT_SUPPORTED

See also

muLibraryUnload​

MUresult muLibraryUnload(MUlibrary library)

Description

  • Unloads a library.
  • Unloads the library specified with library

Parameters

  • library (MUlibrary): Library to unload

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

See also

muLibraryGetKernel​

MUresult muLibraryGetKernel(MUkernel *pKernel, MUlibrary library, const char *name)

Description

  • Returns a kernel handle.
  • Returns in pKernel the handle of the kernel with name name located in library library. If kernel handle is not found, the call returns MUSA_ERROR_NOT_FOUND.

Parameters

  • pKernel (MUkernel *): Returned kernel handle
  • library (MUlibrary): Library to retrieve kernel from
  • name (const char *): Name of kernel to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND

See also

muLibraryGetKernelCount​

MUresult muLibraryGetKernelCount(unsigned int *count, MUlibrary lib)

Description

  • Returns the number of kernels within a library.
  • Returns in count the number of kernels in lib.

Parameters

  • count (unsigned int *): Number of kernels found within the library
  • lib (MUlibrary): Library to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

muLibraryEnumerateKernels​

MUresult muLibraryEnumerateKernels(MUkernel *kernels, unsigned int numKernels, MUlibrary lib)

Description

  • Retrieve the kernel handles within a library.
  • Returns in kernels a maximum number of numKernels kernel handles within lib. The returned kernel handle becomes invalid when the library is unloaded.

Parameters

  • kernels (MUkernel *): Buffer where the kernel handles are returned to
  • numKernels (unsigned int): Maximum number of kernel handles may be returned to the buffer
  • lib (MUlibrary): Library to query from

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muLibraryGetModule​

MUresult muLibraryGetModule(MUmodule *pMod, MUlibrary library)

Description

  • Returns a module handle.
  • Returns in pMod the module handle associated with the current context located in library library. If module handle is not found, the call returns MUSA_ERROR_NOT_FOUND.

Parameters

  • pMod (MUmodule *): Returned module handle
  • library (MUlibrary): Library to retrieve module from

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED

See also

muKernelGetFunction​

MUresult muKernelGetFunction(MUfunction *pFunc, MUkernel kernel)

Description

  • Returns a function handle.
  • Returns in pFunc the handle of the function for the requested kernel kernel and the current context. If function handle is not found, the call returns MUSA_ERROR_NOT_FOUND.

Parameters

  • pFunc (MUfunction *): Returned function handle
  • kernel (MUkernel): Kernel to retrieve function for the requested context

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED

See also

muKernelGetLibrary​

MUresult muKernelGetLibrary(MUlibrary *pLib, MUkernel kernel)

Description

  • Returns a library handle.
  • Returns in pLib the handle of the library for the requested kernel kernel

Parameters

  • pLib (MUlibrary *): Returned library handle
  • kernel (MUkernel): Kernel to retrieve library handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND

See also

muLibraryGetGlobal​

MUresult muLibraryGetGlobal(MUdeviceptr *dptr, size_t *bytes, MUlibrary library, const char *name)

Description

  • Returns a global device pointer.
  • Returns in *dptr and *bytes the base pointer and size of the global with name name for the requested library library and the current context. If no global for the requested name name exists, the call returns MUSA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can be NULL in which case it is ignored.

Parameters

  • dptr (MUdeviceptr *): Returned global device pointer for the requested context
  • bytes (size_t *): Returned global size in bytes
  • library (MUlibrary): Library to retrieve global from
  • name (const char *): Name of global to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED

See also

muLibraryGetManaged​

MUresult muLibraryGetManaged(MUdeviceptr *dptr, size_t *bytes, MUlibrary library, const char *name)

Description

  • Returns a pointer to managed memory.
  • Returns in *dptr and *bytes the base pointer and size of the managed memory with name name for the requested library library. If no managed memory with the requested name name exists, the call returns MUSA_ERROR_NOT_FOUND. One of the parameters dptr or bytes (not both) can be NULL in which case it is ignored. Note that managed memory for library library is shared across devices and is registered when the library is loaded into atleast one context.

Parameters

  • dptr (MUdeviceptr *): Returned pointer to the managed memory
  • bytes (size_t *): Returned memory size in bytes
  • library (MUlibrary): Library to retrieve managed memory from
  • name (const char *): Name of managed memory to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND

See also

muLibraryGetUnifiedFunction​

MUresult muLibraryGetUnifiedFunction(void **fptr, MUlibrary library, const char *symbol)

Description

  • Returns a pointer to a unified function.
  • Returns in *fptr the function pointer to a unified function denoted by symbol. If no unified function with name symbol exists, the call returns MUSA_ERROR_NOT_FOUND. If there is no device with attribute MU_DEVICE_ATTRIBUTE_UNIFIED_FUNCTION_POINTERS present in the system, the call may return MUSA_ERROR_NOT_FOUND.

Parameters

  • fptr (void **): Returned pointer to a unified function
  • library (MUlibrary): Library to retrieve function pointer memory from
  • symbol (const char *): Name of function pointer to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_FOUND

See also

muKernelGetAttribute​

MUresult muKernelGetAttribute(int *pi, MUfunction_attribute attrib, MUkernel kernel, MUdevice dev)

Description

  • Returns information about a kernel.
  • Returns in *pi the integer value of the attribute attrib for the kernel kernel for the requested device dev. The supported attributes are: MU_FUNC_ATTRIBUTE_MAX_THREADS_PER_BLOCK: The maximum number of threads per block, beyond which a launch of the kernel would fail. This number depends on both the kernel and the requested device. MU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES: The size in bytes of statically-allocated shared memory per block required by this kernel. This does not include dynamically-allocated shared memory requested by the user at runtime. MU_FUNC_ATTRIBUTE_CONST_SIZE_BYTES: The size in bytes of user-allocated constant memory required by this kernel. MU_FUNC_ATTRIBUTE_LOCAL_SIZE_BYTES: The size in bytes of local memory used by each thread of this kernel. MU_FUNC_ATTRIBUTE_NUM_REGS: The number of registers used by each thread of this kernel. MU_FUNC_ATTRIBUTE_PTX_VERSION: The PTX virtual architecture version for which the kernel was compiled. This value is the major PTX version * 10 the minor PTX version, so a PTX version 1.3 function would return the value 13. Note that this may return the undefined value of 0 for mubins compiled prior to MUSA 3.0. MU_FUNC_ATTRIBUTE_BINARY_VERSION: The binary architecture version for which the kernel was compiled. This value is the major binary version * 10 + the minor binary version, so a binary version 1.3 function would return the value 13. Note that this will return a value of 10 for legacy mubins that do not have a properly-encoded binary architecture version. MU_FUNC_CACHE_MODE_CA: The attribute to indicate whether the kernel has been compiled with user specified option "-Xptxas --dlcm=ca" set. MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: The maximum size in bytes of dynamically-allocated shared memory. MU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: Preferred shared memory-L1 cache split ratio in percent of total shared memory. MU_FUNC_ATTRIBUTE_CLUSTER_SIZE_MUST_BE_SET: If this attribute is set, the kernel must launch with a valid cluster size specified. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in blocks. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in blocks. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in blocks. MU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed. A non-portable cluster size may only function on the specific SKUs the program is tested on. The launch might fail if the program is run on a different hardware platform. MUSA API provides musaOccupancyMaxActiveClusters to assist with checking whether the desired size can be launched on the current device. A portable cluster size is guaranteed to be functional on all compute capabilities higher than the target compute capability. The portable cluster size for sm_90 is 8 blocks per cluster. This value may increase for future compute capabilities. The specific hardware unit may support higher cluster sizes that’s not guaranteed to be portable. MU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block scheduling policy of a function. The value type is MUclusterSchedulingPolicy.

Parameters

  • pi (int *): Returned attribute value
  • attrib (MUfunction_attribute): Attribute requested
  • kernel (MUkernel): Kernel to query attribute of
  • dev (MUdevice): Device to query attribute of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • If another thread is trying to set the same attribute on the same device using muKernelSetAttribute() simultaneously, the attribute query will give the old or new value depending on the interleavings chosen by the OS scheduler and memory consistency.

See also

muKernelSetAttribute​

MUresult muKernelSetAttribute(MUfunction_attribute attrib, int val, MUkernel kernel, MUdevice dev)

Description

  • Sets information about a kernel.
  • This call sets the value of a specified attribute attrib on the kernel kernel for the requested device dev to an integer value specified by val. This function returns MUSA_SUCCESS if the new value of the attribute could be successfully set. If the set fails, this call will return an error. Not all attributes can have values set. Attempting to set a value on a read-only attribute will result in an error (MUSA_ERROR_INVALID_VALUE)
  • Note that attributes set using muFuncSetAttribute() will override the attribute set by this API irrespective of whether the call to muFuncSetAttribute() is made before or after this API call. However, muKernelGetAttribute() will always return the attribute value set by this API.
  • Supported attributes are: MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: This is the maximum size in bytes of dynamically-allocated shared memory. The value should contain the requested maximum size of dynamically-allocated shared memory. The sum of this value and the function attribute MU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES cannot exceed the device attribute MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_BLOCK_OPTIN. The maximal size of requestable dynamic shared memory may differ by GPU architecture. MU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: On devices where the L1 cache and shared memory use the same hardware resources, this sets the shared memory carveout preference, in percent of the total shared memory. See MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_MULTIPROCESSOR This is only a hint, and the driver can choose a different ratio if required to execute the function. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed. MU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block scheduling policy of a function. The value type is MUclusterSchedulingPolicy.

Parameters

  • attrib (MUfunction_attribute): Attribute requested
  • val (int): Value to set
  • kernel (MUkernel): Kernel to set attribute of
  • dev (MUdevice): Device to set attribute of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • The API has stricter locking requirements in comparison to its legacy counterpart muFuncSetAttribute() due to device-wide semantics. If multiple threads are trying to set the same attribute on the same device simultaneously, the attribute setting will depend on the interleavings chosen by the OS scheduler and memory consistency.

See also

muKernelSetCacheConfig​

MUresult muKernelSetCacheConfig(MUkernel kernel, MUfunc_cache config, MUdevice dev)

Description

  • Sets the preferred cache configuration for a device kernel.
  • On devices where the L1 cache and shared memory use the same hardware resources, this sets through config the preferred cache configuration for the device kernel kernel on the requested device dev. This is only a preference. The driver will use the requested configuration if possible, but it is free to choose a different configuration if required to execute kernel. Any context-wide preference set via muCtxSetCacheConfig() will be overridden by this per-kernel setting.
  • Note that attributes set using muFuncSetCacheConfig() will override the attribute set by this API irrespective of whether the call to muFuncSetCacheConfig() is made before or after this API call.
  • This setting does nothing on devices where the size of the L1 cache and shared memory are fixed.
  • Launching a kernel with a different preference than the most recent preference setting may insert a device-side synchronization point.
  • The supported cache configurations are: MU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default) MU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache MU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory MU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory

Parameters

  • kernel (MUkernel): Kernel to configure cache for
  • config (MUfunc_cache): Requested cache configuration
  • dev (MUdevice): Device to set attribute of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • The API has stricter locking requirements in comparison to its legacy counterpart muFuncSetCacheConfig() due to device-wide semantics. If multiple threads are trying to set a config on the same device simultaneously, the cache config setting will depend on the interleavings chosen by the OS scheduler and memory consistency.

See also

muKernelGetName​

MUresult muKernelGetName(const char **name, MUkernel hfunc)

Description

  • Returns the function name for a MUkernel handle.
  • Returns in **name the function name associated with the kernel handle hfunc . The function name is returned as a null-terminated string. The returned name is only valid when the kernel handle is valid. If the library is unloaded or reloaded, one must call the API again to get the updated name. This API may return a mangled name if the function is not declared as having C linkage. If either **name or hfunc is NULL, MUSA_ERROR_INVALID_VALUE is returned.

Parameters

  • name (const char **): The returned name of the function
  • hfunc (MUkernel): The function handle to retrieve the name for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

muKernelGetParamInfo​

MUresult muKernelGetParamInfo(MUkernel kernel, size_t paramIndex, size_t *paramOffset, size_t *paramSize)

Description

  • Returns the offset and size of a kernel parameter in the device-side parameter layout.
  • Queries the kernel parameter at paramIndex into kernel's list of parameters, and returns in paramOffset and paramSize the offset and size, respectively, where the parameter will reside in the device-side parameter layout. This information can be used to update kernel node parameters from the device via musaGraphKernelNodeSetParam() and musaGraphKernelNodeUpdatesApply(). paramIndex must be less than the number of parameters that kernel takes. paramSize can be set to NULL if only the parameter offset is desired.

Parameters

  • kernel (MUkernel): The kernel to query
  • paramIndex (size_t): The parameter index to query
  • paramOffset (size_t *): Returns the offset into the device-side parameter layout at which the parameter resides
  • paramSize (size_t *): Optionally returns the size of the parameter in the device-side parameter layout

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.12 Memory Management​

muMemGetInfo​

MUresult muMemGetInfo(size_t *free, size_t *total)

Description

  • Gets free and total memory.
  • Returns in *total the total amount of memory available to the the current context. Returns in *free the amount of memory on the device that is free according to the OS. MUSA is not guaranteed to be able to allocate all of the memory that the OS reports as free. In a multi-tenet situation, free estimate returned is prone to race condition where a new allocation/free done by a different process or a different thread in the same process between the time when free memory was estimated and reported, will result in deviation in free value reported and actual free memory.
  • The integrated GPU on Tegra shares memory with CPU and other component of the SoC. The free and total values returned by the API excludes the SWAP memory space maintained by the OS on some platforms. The OS may move some of the memory pages into swap area as the GPU or CPU allocate or access memory. See Tegra app note on how to calculate total and free memory on Tegra.

Parameters

  • free (size_t *): Returned free memory in bytes
  • total (size_t *): Returned total memory in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemGetInfo_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemAlloc​

MUresult muMemAlloc(MUdeviceptr *dptr, size_t bytesize)

Description

  • Allocates device memory.
  • Allocates bytesize bytes of linear memory on the device and returns in *dptr a pointer to the allocated memory. The allocated memory is suitably aligned for any kind of variable. The memory is not cleared. If bytesize is 0, muMemAlloc() returns MUSA_ERROR_INVALID_VALUE.

Parameters

  • dptr (MUdeviceptr *): Returned device pointer
  • bytesize (size_t): Requested allocation size in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muMemAlloc_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemAllocPitch​

MUresult muMemAllocPitch(MUdeviceptr *dptr, size_t *pPitch, size_t WidthInBytes, size_t Height, unsigned int ElementSizeBytes)

Description

  • Allocates pitched device memory.
  • Allocates at least WidthInBytes * Height bytes of linear memory on the device and returns in dptr a pointer to the allocated memory. The function may pad the allocation to ensure that corresponding pointers in any given row will continue to meet the alignment requirements for coalescing as the address is updated from row to row. ElementSizeBytes specifies the size of the largest reads and writes that will be performed on the memory range. ElementSizeBytes may be 4, 8 or 16 (since coalesced memory transactions are not possible on other data sizes). If ElementSizeBytes is smaller than the actual read/write size of a kernel, the kernel will run correctly, but possibly at reduced speed. The pitch returned in pPitch by muMemAllocPitch() is the width in bytes of the allocation. The intended usage of pitch is as a separate parameter of the allocation, used to compute addresses within the 2D array. Given the row and column of an array element of type T, the address is computed as: TpElement=(T)((char*)BaseAddress+Row*Pitch)+Column;
  • The pitch returned by muMemAllocPitch() is guaranteed to work with muMemcpy2D() under all circumstances. For allocations of 2D arrays, it is recommended that programmers consider performing pitch allocations using muMemAllocPitch(). Due to alignment restrictions in the hardware, this is especially true if the application will be performing 2D memory copies between different regions of device memory (whether linear memory or MUSA arrays).
  • The byte alignment of the pitch returned by muMemAllocPitch() is guaranteed to match or exceed the alignment requirement for texture binding with muTexRefSetAddress2D().

Parameters

  • dptr (MUdeviceptr *): Returned device pointer
  • pPitch (size_t *): Returned pitch of allocation in bytes
  • WidthInBytes (size_t): Requested allocation width in bytes
  • Height (size_t): Requested allocation height in rows
  • ElementSizeBytes (unsigned int): Size of largest reads/writes for range

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muMemAllocPitch_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemFree​

MUresult muMemFree(MUdeviceptr dptr)

Description

  • Frees device memory.
  • Frees the memory space pointed to by dptr, which must have been returned by a previous call to one of the following memory allocation APIs - muMemAlloc(), muMemAllocPitch(), muMemAllocManaged(), muMemAllocAsync(), muMemAllocFromPoolAsync()
  • Note - This API will not perform any implict synchronization when the pointer was allocated with muMemAllocAsync or muMemAllocFromPoolAsync. Callers must ensure that all accesses to these pointer have completed before invoking muMemFree. For best performance and memory reuse, users should use muMemFreeAsync to free memory allocated via the stream ordered memory allocator. For all other pointers, this API may perform implicit synchronization.

Parameters

  • dptr (MUdeviceptr): Pointer to memory to free

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemFree_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemGetAddressRange​

MUresult muMemGetAddressRange(MUdeviceptr *pbase, size_t *psize, MUdeviceptr dptr)

Description

  • Get information on memory allocations.
  • Returns the base address in *pbase and size in *psize of the allocation by muMemAlloc() or muMemAllocPitch() that contains the input pointer dptr. Both parameters pbase and psize are optional. If one of them is NULL, it is ignored.

Parameters

  • pbase (MUdeviceptr *): Returned base address
  • psize (size_t *): Returned size of device memory allocation
  • dptr (MUdeviceptr): Device pointer to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_NOT_FOUND, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemGetAddressRange_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemAllocHost​

MUresult muMemAllocHost(void **pp, size_t bytesize)

Description

  • Allocates page-locked host memory.
  • Allocates bytesize bytes of host memory that is page-locked and accessible to the device. The driver tracks the virtual memory ranges allocated with this function and automatically accelerates calls to functions such as muMemcpy(). Since the memory can be accessed directly by the device, it can be read or written with much higher bandwidth than pageable memory obtained with functions such as malloc().
  • On systems where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES is true, muMemAllocHost may not page-lock the allocated memory.
  • Page-locking excessive amounts of memory with muMemAllocHost() may degrade system performance, since it reduces the amount of memory available to the system for paging. As a result, this function is best used sparingly to allocate staging areas for data exchange between host and device.
  • Note all host memory allocated using muMemAllocHost() will automatically be immediately accessible to all contexts on all devices which support unified addressing (as may be queried using MU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING). The device pointer that may be used to access this host memory from those contexts is always equal to the returned host pointer *pp. See Unified Addressing for additional details.

Parameters

  • pp (void **): Returned pointer to host memory
  • bytesize (size_t): Requested allocation size in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muMemAllocHost_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemFreeHost​

MUresult muMemFreeHost(void *p)

Description

  • Frees page-locked host memory.
  • Frees the memory space pointed to by p, which must have been returned by a previous call to muMemAllocHost().

Parameters

  • p (void *): Pointer to memory to free

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemHostAlloc​

MUresult muMemHostAlloc(void **pp, size_t bytesize, unsigned int Flags)

Description

  • Allocates page-locked host memory.
  • Allocates bytesize bytes of host memory that is page-locked and accessible to the device. The driver tracks the virtual memory ranges allocated with this function and automatically accelerates calls to functions such as muMemcpyHtoD(). Since the memory can be accessed directly by the device, it can be read or written with much higher bandwidth than pageable memory obtained with functions such as malloc().
  • On systems where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES is true, muMemHostAlloc may not page-lock the allocated memory.
  • Page-locking excessive amounts of memory may degrade system performance, since it reduces the amount of memory available to the system for paging. As a result, this function is best used sparingly to allocate staging areas for data exchange between host and device.
  • The Flags parameter enables different options to be specified that affect the allocation, as follows.
  • MU_MEMHOSTALLOC_PORTABLE: The memory returned by this call will be considered as pinned memory by all MUSA contexts, not just the one that performed the allocation. MU_MEMHOSTALLOC_DEVICEMAP: Maps the allocation into the MUSA address space. The device pointer to the memory may be obtained by calling muMemHostGetDevicePointer(). MU_MEMHOSTALLOC_WRITECOMBINED: Allocates the memory as write-combined (WC). WC memory can be transferred across the PCI Express bus more quickly on some system configurations, but cannot be read efficiently by most CPUs. WC memory is a good option for buffers that will be written by the CPU and read by the GPU via mapped pinned memory or host->device transfers.
  • All of these flags are orthogonal to one another: a developer may allocate memory that is portable, mapped and/or write-combined with no restrictions.
  • The MU_MEMHOSTALLOC_DEVICEMAP flag may be specified on MUSA contexts for devices that do not support mapped pinned memory. The failure is deferred to muMemHostGetDevicePointer() because the memory may be mapped into other MUSA contexts via the MU_MEMHOSTALLOC_PORTABLE flag.
  • The memory allocated by this function must be freed with muMemFreeHost().
  • Note all host memory allocated using muMemHostAlloc() will automatically be immediately accessible to all contexts on all devices which support unified addressing (as may be queried using MU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING). Unless the flag MU_MEMHOSTALLOC_WRITECOMBINED is specified, the device pointer that may be used to access this host memory from those contexts is always equal to the returned host pointer *pp. If the flag MU_MEMHOSTALLOC_WRITECOMBINED is specified, then the function muMemHostGetDevicePointer() must be used to query the device pointer, even if the context supports unified addressing. See Unified Addressing for additional details.

Parameters

  • pp (void **): Returned pointer to host memory
  • bytesize (size_t): Requested allocation size in bytes
  • Flags (unsigned int): Flags for allocation request

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemHostGetDevicePointer​

MUresult muMemHostGetDevicePointer(MUdeviceptr *pdptr, void *p, unsigned int Flags)

Description

  • Passes back device pointer of mapped pinned memory.
  • Passes back the device pointer pdptr corresponding to the mapped, pinned host buffer p allocated by muMemHostAlloc.
  • muMemHostGetDevicePointer() will fail if the MU_MEMHOSTALLOC_DEVICEMAP flag was not specified at the time the memory was allocated, or if the function is called on a GPU that does not support mapped pinned memory.
  • For devices that have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CAN_USE_HOST_POINTER_FOR_REGISTERED_MEM, the memory can also be accessed from the device using the host pointer p. The device pointer returned by muMemHostGetDevicePointer() may or may not match the original host pointer p and depends on the devices visible to the application. If all devices visible to the application have a non-zero value for the device attribute, the device pointer returned by muMemHostGetDevicePointer() will match the original pointer p. If any device visible to the application has a zero value for the device attribute, the device pointer returned by muMemHostGetDevicePointer() will not match the original host pointer p, but it will be suitable for use on all devices provided Unified Virtual Addressing is enabled. In such systems, it is valid to access the memory using either pointer on devices that have a non-zero value for the device attribute. Note however that such devices should access the memory using only one of the two pointers and not both.
  • Flags provides for future releases. For now, it must be set to 0.

Parameters

  • pdptr (MUdeviceptr *): Returned device pointer
  • p (void *): Host pointer
  • Flags (unsigned int): Options (must be 0)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemHostGetDevicePointer_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemHostGetFlags​

MUresult muMemHostGetFlags(unsigned int *pFlags, void *p)

Description

  • Passes back flags that were used for a pinned allocation.
  • Passes back the flags pFlags that were specified when allocating the pinned host buffer p allocated by muMemHostAlloc.
  • muMemHostGetFlags() will fail if the pointer does not reside in an allocation performed by muMemAllocHost() or muMemHostAlloc().

Parameters

  • pFlags (unsigned int *): Returned flags word
  • p (void *): Host pointer

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemAllocManaged​

MUresult muMemAllocManaged(MUdeviceptr *dptr, size_t bytesize, unsigned int flags)

Description

  • Allocates memory that will be automatically managed by the Unified Memory system.
  • Allocates bytesize bytes of managed memory on the device and returns in *dptr a pointer to the allocated memory. If the device doesn't support allocating managed memory, MUSA_ERROR_NOT_SUPPORTED is returned. Support for managed memory can be queried using the device attribute MU_DEVICE_ATTRIBUTE_MANAGED_MEMORY. The allocated memory is suitably aligned for any kind of variable. The memory is not cleared. If bytesize is 0, muMemAllocManaged returns MUSA_ERROR_INVALID_VALUE. The pointer is valid on the CPU and on all GPUs in the system that support managed memory. All accesses to this pointer must obey the Unified Memory programming model.
  • flags specifies the default stream association for this allocation. flags must be one of MU_MEM_ATTACH_GLOBAL or MU_MEM_ATTACH_HOST. If MU_MEM_ATTACH_GLOBAL is specified, then this memory is accessible from any stream on any device. If MU_MEM_ATTACH_HOST is specified, then the allocation should not be accessed from devices that have a zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS; an explicit call to muStreamAttachMemAsync will be required to enable access on such devices.
  • If the association is later changed via muStreamAttachMemAsync to a single stream, the default association as specified during muMemAllocManaged is restored when that stream is destroyed. For managed variables, the default association is always MU_MEM_ATTACH_GLOBAL. Note that destroying a stream is an asynchronous operation, and as a result, the change to default association won't happen until all work in the stream has completed.
  • Memory allocated with muMemAllocManaged should be released with muMemFree.
  • Device memory oversubscription is possible for GPUs that have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Managed memory on such GPUs may be evicted from device memory to host memory at any time by the Unified Memory driver in order to make room for other allocations.
  • In a system where all GPUs have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS, managed memory may not be populated when this API returns and instead may be populated on access. In such systems, managed memory can migrate to any processor's memory at any time. The Unified Memory driver will employ heuristics to maintain data locality and prevent excessive page faults to the extent possible. The application can also guide the driver about memory usage patterns via muMemAdvise. The application can also explicitly migrate memory to a desired processor's memory via muMemPrefetchAsync.
  • In a multi-GPU system where all of the GPUs have a zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS and all the GPUs have peer-to-peer support with each other, the physical storage for managed memory is created on the GPU which is active at the time muMemAllocManaged is called. All other GPUs will reference the data at reduced bandwidth via peer mappings over the PCIe bus. The Unified Memory driver does not migrate memory among such GPUs.
  • In a multi-GPU system where not all GPUs have peer-to-peer support with each other and where the value of the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS is zero for at least one of those GPUs, the location chosen for physical storage of managed memory is system-dependent. On Linux, the location chosen will be device memory as long as the current set of active contexts are on devices that either have peer-to-peer support with each other or have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. If there is an active context on a GPU that does not have a non-zero value for that device attribute and it does not have peer-to-peer support with the other devices that have active contexts on them, then the location for physical storage will be 'zero-copy' or host memory. Note that this means that managed memory that is located in device memory is migrated to host memory if a new context is created on a GPU that doesn't have a non-zero value for the device attribute and does not support peer-to-peer with at least one of the other devices that has an active context. This in turn implies that context creation may fail if there is insufficient host memory to migrate all managed allocations. On Windows, the physical storage is always created in 'zero-copy' or host memory. All GPUs will reference the data at reduced bandwidth over the PCIe bus. In these circumstances, use of the environment variable MUSA_VISIBLE_DEVICES is recommended to restrict MUSA to only use those GPUs that have peer-to-peer support. Alternatively, users can also set MUSA_MANAGED_FORCE_DEVICE_ALLOC to a non-zero value to force the driver to always use device memory for physical storage. When this environment variable is set to a non-zero value, all contexts created in that process on devices that support managed memory have to be peer-to-peer compatible with each other. Context creation will fail if a context is created on a device that supports managed memory and is not peer-to-peer compatible with any of the other managed memory supporting devices on which contexts were previously created, even if those contexts have been destroyed. These environment variables are described in the MUSA programming guide under the "MUSA environment variables" section. On ARM, managed memory is not available on discrete gpu with Drive PX-2.

Parameters

  • dptr (MUdeviceptr *): Returned device pointer
  • bytesize (size_t): Requested allocation size in bytes
  • flags (unsigned int): Must be one of MU_MEM_ATTACH_GLOBAL or MU_MEM_ATTACH_HOST

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetByPCIBusId​

MUresult muDeviceGetByPCIBusId(MUdevice *dev, const char *pciBusId)

Description

  • Returns a handle to a compute device.
  • Returns in *device a device handle given a PCI bus ID string.

Parameters

  • dev (MUdevice *): Returned device handle
  • pciBusId (const char *): String in one of the following forms:

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetPCIBusId​

MUresult muDeviceGetPCIBusId(char *pciBusId, int len, MUdevice dev)

Description

  • Returns a PCI Bus Id string for the device.
  • Returns an ASCII string identifying the device dev in the NULL-terminated string pointed to by pciBusId. len specifies the maximum length of the string that may be returned.

Parameters

  • pciBusId (char *): Returned identifier string for the device in the following format
  • len (int): Maximum length of string to store in name
  • dev (MUdevice): Device to get identifier string for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muIpcGetEventHandle​

MUresult muIpcGetEventHandle(MUipcEventHandle *pHandle, MUevent event)

Description

  • Gets an interprocess handle for a previously allocated event.
  • Takes as input a previously allocated event. This event must have been created with the MU_EVENT_INTERPROCESS and MU_EVENT_DISABLE_TIMING flags set. This opaque handle may be copied into other processes and opened with muIpcOpenEventHandle to allow efficient hardware synchronization between GPU work in different processes.
  • After the event has been opened in the importing process, muEventRecord, muEventSynchronize, muStreamWaitEvent and muEventQuery may be used in either process. Performing operations on the imported event after the exported event has been freed with muEventDestroy will result in undefined behavior.
  • IPC functionality is restricted to devices with support for unified addressing on Linux and Windows operating systems. IPC functionality on Windows is supported for compatibility purposes but not recommended as it comes with performance cost. Users can test their device for IPC functionality by calling muapiDeviceGetAttribute with MU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Parameters

  • pHandle (MUipcEventHandle *): Pointer to a user allocated MUipcEventHandle in which to return the opaque event handle
  • event (MUevent): Event allocated with MU_EVENT_INTERPROCESS and MU_EVENT_DISABLE_TIMING flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_MAP_FAILED, MUSA_ERROR_INVALID_VALUE

See also

muIpcOpenEventHandle​

MUresult muIpcOpenEventHandle(MUevent *phEvent, MUipcEventHandle handle)

Description

  • Opens an interprocess event handle for use in the current process.
  • Opens an interprocess event handle exported from another process with muIpcGetEventHandle. This function returns a MUevent that behaves like a locally created event with the MU_EVENT_DISABLE_TIMING flag specified. This event must be freed with muEventDestroy.
  • Performing operations on the imported event after the exported event has been freed with muEventDestroy will result in undefined behavior.
  • IPC functionality is restricted to devices with support for unified addressing on Linux and Windows operating systems. IPC functionality on Windows is supported for compatibility purposes but not recommended as it comes with performance cost. Users can test their device for IPC functionality by calling muapiDeviceGetAttribute with MU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Parameters

  • phEvent (MUevent *): Returns the imported event
  • handle (MUipcEventHandle): Interprocess handle to open

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_MAP_FAILED, MUSA_ERROR_PEER_ACCESS_UNSUPPORTED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muIpcGetMemHandle​

MUresult muIpcGetMemHandle(MUipcMemHandle *pHandle, MUdeviceptr dptr)

Description

  • Gets an interprocess memory handle for an existing device memory allocation.
  • Takes a pointer to the base of an existing device memory allocation created with muMemAlloc and exports it for use in another process. This is a lightweight operation and may be called multiple times on an allocation without adverse effects.
  • If a region of memory is freed with muMemFree and a subsequent call to muMemAlloc returns memory with the same device address, muIpcGetMemHandle will return a unique handle for the new memory.
  • IPC functionality is restricted to devices with support for unified addressing on Linux and Windows operating systems. IPC functionality on Windows is supported for compatibility purposes but not recommended as it comes with performance cost. Users can test their device for IPC functionality by calling muapiDeviceGetAttribute with MU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Parameters

  • pHandle (MUipcMemHandle *): Pointer to user allocated MUipcMemHandle to return the handle in.
  • dptr (MUdeviceptr): Base pointer to previously allocated device memory

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_MAP_FAILED, MUSA_ERROR_INVALID_VALUE

See also

muIpcOpenMemHandle​

MUresult muIpcOpenMemHandle(MUdeviceptr *pdptr, MUipcMemHandle handle, unsigned int Flags)

Description

  • Opens an interprocess memory handle exported from another process and returns a device pointer usable in the local process.
  • Maps memory exported from another process with muIpcGetMemHandle into the current device address space. For contexts on different devices muIpcOpenMemHandle can attempt to enable peer access between the devices as if the user called muCtxEnablePeerAccess. This behavior is controlled by the MU_IPC_MEM_LAZY_ENABLE_PEER_ACCESS flag. muDeviceCanAccessPeer can determine if a mapping is possible.
  • Contexts that may open MUipcMemHandles are restricted in the following way. MUipcMemHandles from each MUdevice in a given process may only be opened by one MUcontext per MUdevice per other process.
  • If the memory handle has already been opened by the current context, the reference count on the handle is incremented by 1 and the existing device pointer is returned.
  • Memory returned from muIpcOpenMemHandle must be freed with muIpcCloseMemHandle.
  • Calling muMemFree on an exported memory region before calling muIpcCloseMemHandle in the importing context will result in undefined behavior.
  • IPC functionality is restricted to devices with support for unified addressing on Linux and Windows operating systems. IPC functionality on Windows is supported for compatibility purposes but not recommended as it comes with performance cost. Users can test their device for IPC functionality by calling muapiDeviceGetAttribute with MU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Parameters

  • pdptr (MUdeviceptr *): Returned device pointer
  • handle (MUipcMemHandle): MUipcMemHandle to open
  • Flags (unsigned int): Flags for this operation. Must be specified as MU_IPC_MEM_LAZY_ENABLE_PEER_ACCESS

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_MAP_FAILED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_TOO_MANY_PEERS, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muIpcOpenMemHandle_v2.
  • No guarantees are made about the address returned in *pdptr. In particular, multiple processes may not receive the same address for the same handle.

See also

muIpcCloseMemHandle​

MUresult muIpcCloseMemHandle(MUdeviceptr dptr)

Description

  • Attempts to close memory mapped with muIpcOpenMemHandle.
  • Decrements the reference count of the memory returned by muIpcOpenMemHandle by 1. When the reference count reaches 0, this API unmaps the memory. The original allocation in the exporting process as well as imported mappings in other processes will be unaffected.
  • Any resources used to enable peer access will be freed if this is the last mapping using them.
  • IPC functionality is restricted to devices with support for unified addressing on Linux and Windows operating systems. IPC functionality on Windows is supported for compatibility purposes but not recommended as it comes with performance cost. Users can test their device for IPC functionality by calling muapiDeviceGetAttribute with MU_DEVICE_ATTRIBUTE_IPC_EVENT_SUPPORTED

Parameters

  • dptr (MUdeviceptr): Device pointer returned by muIpcOpenMemHandle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_MAP_FAILED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muMemHostRegister​

MUresult muMemHostRegister(void *p, size_t bytesize, unsigned int Flags)

Description

  • Registers an existing host memory range for use by MUSA.
  • Page-locks the memory range specified by p and bytesize and maps it for the device(s) as specified by Flags. This memory range also is added to the same tracking mechanism as muMemHostAlloc to automatically accelerate calls to functions such as muMemcpyHtoD(). Since the memory can be accessed directly by the device, it can be read or written with much higher bandwidth than pageable memory that has not been registered. Page-locking excessive amounts of memory may degrade system performance, since it reduces the amount of memory available to the system for paging. As a result, this function is best used sparingly to register staging areas for data exchange between host and device.
  • On systems where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES is true, muMemHostRegister will not page-lock the memory range specified by ptr but only populate unpopulated pages.
  • The Flags parameter enables different options to be specified that affect the allocation, as follows.
  • MU_MEMHOSTREGISTER_PORTABLE: The memory returned by this call will be considered as pinned memory by all MUSA contexts, not just the one that performed the allocation. MU_MEMHOSTREGISTER_DEVICEMAP: Maps the allocation into the MUSA address space. The device pointer to the memory may be obtained by calling muMemHostGetDevicePointer(). MU_MEMHOSTREGISTER_IOMEMORY: The pointer is treated as pointing to some I/O memory space, e.g. the PCI Express resource of a 3rd party device. MU_MEMHOSTREGISTER_READ_ONLY: The pointer is treated as pointing to memory that is considered read-only by the device. On platforms without MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, this flag is required in order to register memory mapped to the CPU as read-only. Support for the use of this flag can be queried from the device attribute MU_DEVICE_ATTRIBUTE_READ_ONLY_HOST_REGISTER_SUPPORTED. Using this flag with a current context associated with a device that does not have this attribute set will cause muMemHostRegister to error with MUSA_ERROR_NOT_SUPPORTED.
  • All of these flags are orthogonal to one another: a developer may page-lock memory that is portable or mapped with no restrictions.
  • The MU_MEMHOSTREGISTER_DEVICEMAP flag may be specified on MUSA contexts for devices that do not support mapped pinned memory. The failure is deferred to muMemHostGetDevicePointer() because the memory may be mapped into other MUSA contexts via the MU_MEMHOSTREGISTER_PORTABLE flag.
  • For devices that have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CAN_USE_HOST_POINTER_FOR_REGISTERED_MEM, the memory can also be accessed from the device using the host pointer p. The device pointer returned by muMemHostGetDevicePointer() may or may not match the original host pointer ptr and depends on the devices visible to the application. If all devices visible to the application have a non-zero value for the device attribute, the device pointer returned by muMemHostGetDevicePointer() will match the original pointer ptr. If any device visible to the application has a zero value for the device attribute, the device pointer returned by muMemHostGetDevicePointer() will not match the original host pointer ptr, but it will be suitable for use on all devices provided Unified Virtual Addressing is enabled. In such systems, it is valid to access the memory using either pointer on devices that have a non-zero value for the device attribute. Note however that such devices should access the memory using only of the two pointers and not both.
  • The memory page-locked by this function must be unregistered with muMemHostUnregister().

Parameters

  • p (void *): Host pointer to memory to page-lock
  • bytesize (size_t): Size in bytes of the address range to page-lock
  • Flags (unsigned int): Flags for allocation request

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_HOST_MEMORY_ALREADY_REGISTERED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muMemHostRegister_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemHostUnregister​

MUresult muMemHostUnregister(void *p)

Description

  • Unregisters a memory range that was registered with muMemHostRegister.
  • Unmaps the memory range whose base address is specified by p, and makes it pageable again.
  • The base address must be the same one specified to muMemHostRegister().

Parameters

  • p (void *): Host pointer to memory to unregister

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_HOST_MEMORY_NOT_REGISTERED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemcpy​

MUresult muMemcpy(MUdeviceptr dst, MUdeviceptr src, size_t ByteCount)

Description

  • Copies memory.
  • Copies data between two pointers. dst and src are base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy. Note that this function infers the type of the transfer (host to host, host to device, device to device, or device to host) from the pointer values. This function is only allowed in contexts which support unified addressing.

Parameters

  • dst (MUdeviceptr): Destination unified virtual address space pointer
  • src (MUdeviceptr): Source unified virtual address space pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpy_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyPeer​

MUresult muMemcpyPeer(MUdeviceptr dstDevice, MUcontext dstContext, MUdeviceptr srcDevice, MUcontext srcContext, size_t ByteCount)

Description

  • Copies device memory between two contexts.
  • Copies from device memory in one context to device memory in another context. dstDevice is the base device pointer of the destination memory and dstContext is the destination context. srcDevice is the base device pointer of the source memory and srcContext is the source pointer. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstContext (MUcontext): Destination context
  • srcDevice (MUdeviceptr): Source device pointer
  • srcContext (MUcontext): Source context
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyHtoD​

MUresult muMemcpyHtoD(MUdeviceptr dstDevice, const void *srcHost, size_t ByteCount)

Description

  • Copies memory from Host to Device.
  • Copies from host memory to device memory. dstDevice and srcHost are the base addresses of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • srcHost (const void *): Source host pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyHtoD_v2, muMemcpyHtoD_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyDtoH​

MUresult muMemcpyDtoH(void *dstHost, MUdeviceptr srcDevice, size_t ByteCount)

Description

  • Copies memory from Device to Host.
  • Copies from device to host memory. dstHost and srcDevice specify the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstHost (void *): Destination host pointer
  • srcDevice (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyDtoH_v2, muMemcpyDtoH_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyDtoD​

MUresult muMemcpyDtoD(MUdeviceptr dstDevice, MUdeviceptr srcDevice, size_t ByteCount)

Description

  • Copies memory from Device to Device.
  • Copies from device memory to device memory. dstDevice and srcDevice are the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • srcDevice (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyDtoD_v2, muMemcpyDtoD_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyDtoA​

MUresult muMemcpyDtoA(MUarray dstArray, size_t dstOffset, MUdeviceptr srcDevice, size_t ByteCount)

Description

  • Copies memory from Device to Array.
  • Copies from device memory to a 1D MUSA array. dstArray and dstOffset specify the MUSA array handle and starting index of the destination data. srcDevice specifies the base pointer of the source. ByteCount specifies the number of bytes to copy.

Parameters

  • dstArray (MUarray): Destination array
  • dstOffset (size_t): Offset in bytes of destination array
  • srcDevice (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyDtoA_v2, muMemcpyDtoA_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyAtoD​

MUresult muMemcpyAtoD(MUdeviceptr dstDevice, MUarray srcArray, size_t srcOffset, size_t ByteCount)

Description

  • Copies memory from Array to Device.
  • Copies from one 1D MUSA array to device memory. dstDevice specifies the base pointer of the destination and must be naturally aligned with the MUSA array elements. srcArray and srcOffset specify the MUSA array handle and the offset in bytes into the array where the copy is to begin. ByteCount specifies the number of bytes to copy and must be evenly divisible by the array element size.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • srcArray (MUarray): Source array
  • srcOffset (size_t): Offset in bytes of source array
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyAtoD_v2, muMemcpyAtoD_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyHtoA​

MUresult muMemcpyHtoA(MUarray dstArray, size_t dstOffset, const void *srcHost, size_t ByteCount)

Description

  • Copies memory from Host to Array.
  • Copies from host memory to a 1D MUSA array. dstArray and dstOffset specify the MUSA array handle and starting offset in bytes of the destination data. pSrc specifies the base address of the source. ByteCount specifies the number of bytes to copy.

Parameters

  • dstArray (MUarray): Destination array
  • dstOffset (size_t): Offset in bytes of destination array
  • srcHost (const void *): Source host pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyHtoA_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyAtoH​

MUresult muMemcpyAtoH(void *dstHost, MUarray srcArray, size_t srcOffset, size_t ByteCount)

Description

  • Copies memory from Array to Host.
  • Copies from one 1D MUSA array to host memory. dstHost specifies the base pointer of the destination. srcArray and srcOffset specify the MUSA array handle and starting offset in bytes of the source data. ByteCount specifies the number of bytes to copy.

Parameters

  • dstHost (void *): Destination device pointer
  • srcArray (MUarray): Source array
  • srcOffset (size_t): Offset in bytes of source array
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyAtoH_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyAtoA​

MUresult muMemcpyAtoA(MUarray dstArray, size_t dstOffset, MUarray srcArray, size_t srcOffset, size_t ByteCount)

Description

  • Copies memory from Array to Array.
  • Copies from one 1D MUSA array to another. dstArray and srcArray specify the handles of the destination and source MUSA arrays for the copy, respectively. dstOffset and srcOffset specify the destination and source offsets in bytes into the MUSA arrays. ByteCount is the number of bytes to be copied. The size of the elements in the MUSA arrays need not be the same format, but the elements must be the same size; and count must be evenly divisible by that size.

Parameters

  • dstArray (MUarray): Destination array
  • dstOffset (size_t): Offset in bytes of destination array
  • srcArray (MUarray): Source array
  • srcOffset (size_t): Offset in bytes of source array
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpyAtoA_v2, muMemcpyAtoA_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpy2D​

MUresult muMemcpy2D(const MUSA_MEMCPY2D *pCopy)

Description

  • Copies memory for 2D arrays.
  • Perform a 2D memory copy according to the parameters specified in pCopy. The MUSA_MEMCPY2D structure is defined as:
typedef struct MUSA_MEMCPY2D_st {
  unsigned int srcXInBytes, srcY;
  MUmemorytype srcMemoryType;
  const void *srcHost;
  MUdeviceptr srcDevice;
  MUarray srcArray;
  unsigned int srcPitch;
  unsigned int dstXInBytes, dstY;
  MUmemorytype dstMemoryType;
  void *dstHost;
  MUdeviceptr dstDevice;
  MUarray dstArray;
  unsigned int dstPitch;
  unsigned int WidthInBytes;
  unsigned int Height;
} MUSA_MEMCPY2D;
  • where: srcMemoryType and dstMemoryType specify the type of memory of the source and destination, respectively; MUmemorytype_enum is defined as:
typedef enum MUmemorytype_enum {
  MU_MEMORYTYPE_HOST = 0x01,
  MU_MEMORYTYPE_DEVICE = 0x02,
  MU_MEMORYTYPE_ARRAY = 0x03,
  MU_MEMORYTYPE_UNIFIED = 0x04;
} MUmemorytype;

Parameters

  • pCopy (const MUSA_MEMCPY2D *): Parameters for the memory copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpy2D_v2, muMemcpy2D_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpy2DUnaligned​

MUresult muMemcpy2DUnaligned(const MUSA_MEMCPY2D *pCopy)

Description

  • Copies memory for 2D arrays.
  • Perform a 2D memory copy according to the parameters specified in pCopy. The MUSA_MEMCPY2D structure is defined as:
typedef struct MUSA_MEMCPY2D_st {
  unsigned int srcXInBytes, srcY;
  MUmemorytype srcMemoryType;
  const void *srcHost;
  MUdeviceptr srcDevice;
  MUarray srcArray;
  unsigned int srcPitch;
  unsigned int dstXInBytes, dstY;
  MUmemorytype dstMemoryType;
  void *dstHost;
  MUdeviceptr dstDevice;
  MUarray dstArray;
  unsigned int dstPitch;
  unsigned int WidthInBytes;
  unsigned int Height;
} MUSA_MEMCPY2D;
  • where: srcMemoryType and dstMemoryType specify the type of memory of the source and destination, respectively; MUmemorytype_enum is defined as:
typedef enum MUmemorytype_enum {
  MU_MEMORYTYPE_HOST = 0x01,
  MU_MEMORYTYPE_DEVICE = 0x02,
  MU_MEMORYTYPE_ARRAY = 0x03,
  MU_MEMORYTYPE_UNIFIED = 0x04;
} MUmemorytype;

Parameters

  • pCopy (const MUSA_MEMCPY2D *): Parameters for the memory copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpy2DUnaligned_v2, muMemcpy2DUnaligned_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpy3D​

MUresult muMemcpy3D(const MUSA_MEMCPY3D *pCopy)

Description

  • Copies memory for 3D arrays.
  • Perform a 3D memory copy according to the parameters specified in pCopy. The MUSA_MEMCPY3D structure is defined as:
typedef struct MUSA_MEMCPY3D_st {
  unsigned int srcXInBytes, srcY, srcZ;
  unsigned int srcLOD;
  MUmemorytype srcMemoryType;
  const void *srcHost;
  MUdeviceptr srcDevice;
  MUarray srcArray;
  unsigned int srcPitch;
  //ignoredwhensrcisarray unsigned int srcHeight;
  //ignoredwhensrcisarray;
  maybe0ifDepth==1 unsigned int dstXInBytes, dstY, dstZ;
  unsigned int dstLOD;
  MUmemorytype dstMemoryType;
  void *dstHost;
  MUdeviceptr dstDevice;
  MUarray dstArray;
  unsigned int dstPitch;
  //ignoredwhendstisarray unsigned int dstHeight;
  //ignoredwhendstisarray;
  maybe0ifDepth==1 unsigned int WidthInBytes;
  unsigned int Height;
  unsigned int Depth;
} MUSA_MEMCPY3D;
  • where: srcMemoryType and dstMemoryType specify the type of memory of the source and destination, respectively; MUmemorytype_enum is defined as:
typedef enum MUmemorytype_enum {
  MU_MEMORYTYPE_HOST = 0x01,
  MU_MEMORYTYPE_DEVICE = 0x02,
  MU_MEMORYTYPE_ARRAY = 0x03,
  MU_MEMORYTYPE_UNIFIED = 0x04;
} MUmemorytype;

Parameters

  • pCopy (const MUSA_MEMCPY3D *): Parameters for the memory copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemcpy3D_v2, muMemcpy3D_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpy3DPeer​

MUresult muMemcpy3DPeer(const MUSA_MEMCPY3D_PEER *pCopy)

Description

  • Copies memory between contexts.
  • Perform a 3D memory copy according to the parameters specified in pCopy. See the definition of the MUSA_MEMCPY3D_PEER structure for documentation of its parameters.

Parameters

  • pCopy (const MUSA_MEMCPY3D_PEER *): Parameters for the memory copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemcpyAsync​

MUresult muMemcpyAsync(MUdeviceptr dst, MUdeviceptr src, size_t ByteCount, MUstream hStream)

Description

  • Copies memory asynchronously.
  • Copies data between two pointers. dst and src are base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy. Note that this function infers the type of the transfer (host to host, host to device, device to device, or device to host) from the pointer values. This function is only allowed in contexts which support unified addressing.

Parameters

  • dst (MUdeviceptr): Destination unified virtual address space pointer
  • src (MUdeviceptr): Source unified virtual address space pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyAsync_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyPeerAsync​

MUresult muMemcpyPeerAsync(MUdeviceptr dstDevice, MUcontext dstContext, MUdeviceptr srcDevice, MUcontext srcContext, size_t ByteCount, MUstream hStream)

Description

  • Copies device memory between two contexts asynchronously.
  • Copies from device memory in one context to device memory in another context. dstDevice is the base device pointer of the destination memory and dstContext is the destination context. srcDevice is the base device pointer of the source memory and srcContext is the source pointer. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstContext (MUcontext): Destination context
  • srcDevice (MUdeviceptr): Source device pointer
  • srcContext (MUcontext): Source context
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyHtoDAsync​

MUresult muMemcpyHtoDAsync(MUdeviceptr dstDevice, const void *srcHost, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Host to Device.
  • Copies from host memory to device memory. dstDevice and srcHost are the base addresses of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • srcHost (const void *): Source host pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyHtoDAsync_v2, muMemcpyHtoDAsync_v2_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyDtoHAsync​

MUresult muMemcpyDtoHAsync(void *dstHost, MUdeviceptr srcDevice, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Device to Host.
  • Copies from device to host memory. dstHost and srcDevice specify the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstHost (void *): Destination host pointer
  • srcDevice (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyDtoHAsync_v2, muMemcpyDtoHAsync_v2_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyDtoDAsync​

MUresult muMemcpyDtoDAsync(MUdeviceptr dstDevice, MUdeviceptr srcDevice, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Device to Device.
  • Copies from device memory to device memory. dstDevice and srcDevice are the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • srcDevice (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyDtoDAsync_v2, muMemcpyDtoDAsync_v2_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyHtoAAsync​

MUresult muMemcpyHtoAAsync(MUarray dstArray, size_t dstOffset, const void *srcHost, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Host to Array.
  • Copies from host memory to a 1D MUSA array. dstArray and dstOffset specify the MUSA array handle and starting offset in bytes of the destination data. srcHost specifies the base address of the source. ByteCount specifies the number of bytes to copy.

Parameters

  • dstArray (MUarray): Destination array
  • dstOffset (size_t): Offset in bytes of destination array
  • srcHost (const void *): Source host pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyHtoAAsync_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyAtoHAsync​

MUresult muMemcpyAtoHAsync(void *dstHost, MUarray srcArray, size_t srcOffset, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Array to Host.
  • Copies from one 1D MUSA array to host memory. dstHost specifies the base pointer of the destination. srcArray and srcOffset specify the MUSA array handle and starting offset in bytes of the source data. ByteCount specifies the number of bytes to copy.

Parameters

  • dstHost (void *): Destination pointer
  • srcArray (MUarray): Source array
  • srcOffset (size_t): Offset in bytes of source array
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpyAtoHAsync_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpy2DAsync​

MUresult muMemcpy2DAsync(const MUSA_MEMCPY2D *pCopy, MUstream hStream)

Description

  • Copies memory for 2D arrays.
  • Perform a 2D memory copy according to the parameters specified in pCopy. The MUSA_MEMCPY2D structure is defined as:
typedef struct MUSA_MEMCPY2D_st {
  unsigned int srcXInBytes, srcY;
  MUmemorytype srcMemoryType;
  const void *srcHost;
  MUdeviceptr srcDevice;
  MUarray srcArray;
  unsigned int srcPitch;
  unsigned int dstXInBytes, dstY;
  MUmemorytype dstMemoryType;
  void *dstHost;
  MUdeviceptr dstDevice;
  MUarray dstArray;
  unsigned int dstPitch;
  unsigned int WidthInBytes;
  unsigned int Height;
} MUSA_MEMCPY2D;
  • where: srcMemoryType and dstMemoryType specify the type of memory of the source and destination, respectively; MUmemorytype_enum is defined as:
typedef enum MUmemorytype_enum {
  MU_MEMORYTYPE_HOST = 0x01,
  MU_MEMORYTYPE_DEVICE = 0x02,
  MU_MEMORYTYPE_ARRAY = 0x03,
  MU_MEMORYTYPE_UNIFIED = 0x04;
} MUmemorytype;

Parameters

  • pCopy (const MUSA_MEMCPY2D *): Parameters for the memory copy
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpy2DAsync_v2, muMemcpy2DAsync_v2_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpy3DAsync​

MUresult muMemcpy3DAsync(const MUSA_MEMCPY3D *pCopy, MUstream hStream)

Description

  • Copies memory for 3D arrays.
  • Perform a 3D memory copy according to the parameters specified in pCopy. The MUSA_MEMCPY3D structure is defined as:
typedef struct MUSA_MEMCPY3D_st {
  unsigned int srcXInBytes, srcY, srcZ;
  unsigned int srcLOD;
  MUmemorytype srcMemoryType;
  const void *srcHost;
  MUdeviceptr srcDevice;
  MUarray srcArray;
  unsigned int srcPitch;
  //ignoredwhensrcisarray unsigned int srcHeight;
  //ignoredwhensrcisarray;
  maybe0ifDepth==1 unsigned int dstXInBytes, dstY, dstZ;
  unsigned int dstLOD;
  MUmemorytype dstMemoryType;
  void *dstHost;
  MUdeviceptr dstDevice;
  MUarray dstArray;
  unsigned int dstPitch;
  //ignoredwhendstisarray unsigned int dstHeight;
  //ignoredwhendstisarray;
  maybe0ifDepth==1 unsigned int WidthInBytes;
  unsigned int Height;
  unsigned int Depth;
} MUSA_MEMCPY3D;
  • where: srcMemoryType and dstMemoryType specify the type of memory of the source and destination, respectively; MUmemorytype_enum is defined as:
typedef enum MUmemorytype_enum {
  MU_MEMORYTYPE_HOST = 0x01,
  MU_MEMORYTYPE_DEVICE = 0x02,
  MU_MEMORYTYPE_ARRAY = 0x03,
  MU_MEMORYTYPE_UNIFIED = 0x04;
} MUmemorytype;

Parameters

  • pCopy (const MUSA_MEMCPY3D *): Parameters for the memory copy
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemcpy3DAsync_v2, muMemcpy3DAsync_v2_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpy3DPeerAsync​

MUresult muMemcpy3DPeerAsync(const MUSA_MEMCPY3D_PEER *pCopy, MUstream hStream)

Description

  • Copies memory between contexts asynchronously.
  • Perform a 3D memory copy according to the parameters specified in pCopy. See the definition of the MUSA_MEMCPY3D_PEER structure for documentation of its parameters.

Parameters

  • pCopy (const MUSA_MEMCPY3D_PEER *): Parameters for the memory copy
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemcpyBatchAsync​

MUresult muMemcpyBatchAsync(MUdeviceptr *dsts, MUdeviceptr *srcs, size_t *sizes, size_t count, MUmemcpyAttributes *attrs, size_t *attrsIdxs, size_t numAttrs, size_t *failIdx, MUstream hStream)

Description

  • Performs a batch of memory copies asynchronously.
  • Performs a batch of memory copies. The batch as a whole executes in stream order but copies within a batch are not guaranteed to execute in any specific order. This API only supports pointer-to-pointer copies. For copies involving MUSA arrays, please see muMemcpy3DBatchAsync.
  • Performs memory copies from source buffers specified in srcs to destination buffers specified in dsts. The size of each copy is specified in sizes. All three arrays must be of the same length as specified by count. Since there are no ordering guarantees for copies within a batch, specifying any dependent copies within a batch will result in undefined behavior.
  • Every copy in the batch has to be associated with a set of attributes specified in the attrs array. Each entry in this array can apply to more than one copy. This can be done by specifying in the attrsIdxs array, the index of the first copy that the corresponding entry in the attrs array applies to. Both attrs and attrsIdxs must be of the same length as specified by numAttrs. For example, if a batch has 10 copies listed in dst/src/sizes, the first 6 of which have one set of attributes and the remaining 4 another, then numAttrs will be 2, attrsIdxs will be {0, 6} and attrs will contains the two sets of attributes. Note that the first entry in attrsIdxs must always be 0. Also, each entry must be greater than the previous entry and the last entry should be less than count. Furthermore, numAttrs must be lesser than or equal to count.
  • The MUmemcpyAttributes::srcAccessOrder indicates the source access ordering to be observed for copies associated with the attribute. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_STREAM, then the source will be accessed in stream order. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_DURING_API_CALL then it indicates that access to the source pointer can be out of stream order and all accesses must be complete before the API call returns. This flag is suited for ephemeral sources (ex., stack variables) when it's known that no prior operations in the stream can be accessing the memory and also that the lifetime of the memory is limited to the scope that the source variable was declared in. Specifying this flag allows the driver to optimize the copy and removes the need for the user to synchronize the stream after the API call. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_ANY then it indicates that access to the source pointer can be out of stream order and the accesses can happen even after the API call returns. This flag is suited for host pointers allocated outside MUSA (ex., via malloc) when it's known that no prior operations in the stream can be accessing the memory. Specifying this flag allows the driver to optimize the copy on certain platforms. Each memcpy operation in the batch must have a valid MUmemcpyAttributes corresponding to it including the appropriate srcAccessOrder setting, otherwise the API will return MUSA_ERROR_INVALID_VALUE.
  • The MUmemcpyAttributes::srcLocHint and MUmemcpyAttributes::dstLocHint allows applications to specify hint locations for operands of a copy when the operand doesn't have a fixed location. That is, these hints are only applicable for managed memory pointers on devices where MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS is true or system-allocated pageable memory on devices where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS is true. For other cases, these hints are ignored.
  • The MUmemcpyAttributes::flags field can be used to specify certain flags for copies. Setting the MU_MEMCPY_FLAG_PREFER_OVERLAP_WITH_COMPUTE flag indicates that the associated copies should preferably overlap with any compute work. Note that this flag is a hint and can be ignored depending on the platform and other parameters of the copy.
  • If any error is encountered while parsing the batch, the index within the batch where the error was encountered will be returned in failIdx.

Parameters

  • dsts (MUdeviceptr *): Array of destination pointers.
  • srcs (MUdeviceptr *): Array of memcpy source pointers.
  • sizes (size_t *): Array of sizes for memcpy operations.
  • count (size_t): Size of dsts, srcs and sizes arrays
  • attrs (MUmemcpyAttributes *): Array of memcpy attributes.
  • attrsIdxs (size_t *): Array of indices to specify which copies each entry in the attrs array applies to. The attributes specified in attrs[k] will be applied to copies starting from attrsIdxs[k] through attrsIdxs[k+1] - 1. Also attrs[numAttrs-1] will apply to copies starting from attrsIdxs[numAttrs-1] through count - 1.
  • numAttrs (size_t): Size of attrs and attrsIdxs arrays.
  • failIdx (size_t *): Pointer to a location to return the index of the copy where a failure was encountered. The value will be SIZE_MAX if the error doesn't pertain to any specific copy.
  • hStream (MUstream): The stream to enqueue the operations in. Must not be legacy NULL stream.

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED MUSA_ERROR_NOT_INITIALIZED MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.

muMemoryTransferBatchAsync​

MUresult muMemoryTransferBatchAsync(MUdeviceptr *dsts, MUdeviceptr *srcs, size_t *sizes, size_t count, MUmemcpyAttributes *attrs, size_t *attrsIdxs, size_t numAttrs, size_t *failIdx, MUstream hStream)

Description

  • Performs a batch of memory copies asynchronously, and the memory can't be pinned host memory, now just support d2d and p2p.
  • Performs a batch of memory copies. The batch as a whole executes in stream order but copies within a batch are not guaranteed to execute in any specific order. This API only supports pointer-to-pointer copies. For copies involving MUSA arrays, please see muMemcpy3DBatchAsync.
  • Performs memory copies from source buffers specified in srcs to destination buffers specified in dsts. The size of each copy is specified in sizes. All three arrays must be of the same length as specified by count. Since there are no ordering guarantees for copies within a batch, specifying any dependent copies within a batch will result in undefined behavior.
  • Every copy in the batch has to be associated with a set of attributes specified in the attrs array. Each entry in this array can apply to more than one copy. This can be done by specifying in the attrsIdxs array, the index of the first copy that the corresponding entry in the attrs array applies to. Both attrs and attrsIdxs must be of the same length as specified by numAttrs. For example, if a batch has 10 copies listed in dst/src/sizes, the first 6 of which have one set of attributes and the remaining 4 another, then numAttrs will be 2, attrsIdxs will be {0, 6} and attrs will contains the two sets of attributes. Note that the first entry in attrsIdxs must always be 0. Also, each entry must be greater than the previous entry and the last entry should be less than count. Furthermore, numAttrs must be lesser than or equal to count.
  • The MUmemcpyAttributes::srcAccessOrder indicates the source access ordering to be observed for copies associated with the attribute. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_STREAM, then the source will be accessed in stream order. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_DURING_API_CALL then it indicates that access to the source pointer can be out of stream order and all accesses must be complete before the API call returns. This flag is suited for ephemeral sources (ex., stack variables) when it's known that no prior operations in the stream can be accessing the memory and also that the lifetime of the memory is limited to the scope that the source variable was declared in. Specifying this flag allows the driver to optimize the copy and removes the need for the user to synchronize the stream after the API call. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_ANY then it indicates that access to the source pointer can be out of stream order and the accesses can happen even after the API call returns. This flag is suited for host pointers allocated outside MUSA (ex., via malloc) when it's known that no prior operations in the stream can be accessing the memory. Specifying this flag allows the driver to optimize the copy on certain platforms. Each memcpy operation in the batch must have a valid MUmemcpyAttributes corresponding to it including the appropriate srcAccessOrder setting, otherwise the API will return MUSA_ERROR_INVALID_VALUE.
  • The MUmemcpyAttributes::srcLocHint and MUmemcpyAttributes::dstLocHint allows applications to specify hint locations for operands of a copy when the operand doesn't have a fixed location. That is, these hints are only applicable for managed memory pointers on devices where MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS is true or system-allocated pageable memory on devices where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS is true. For other cases, these hints are ignored.
  • The MUmemcpyAttributes::flags field can be used to specify certain flags for copies. Setting the MU_MEMCPY_FLAG_PREFER_OVERLAP_WITH_COMPUTE flag indicates that the associated copies should preferably overlap with any compute work. Note that this flag is a hint and can be ignored depending on the platform and other parameters of the copy.
  • If any error is encountered while parsing the batch, the index within the batch where the error was encountered will be returned in failIdx.

Parameters

  • dsts (MUdeviceptr *): Array of destination pointers.
  • srcs (MUdeviceptr *): Array of memcpy source pointers.
  • sizes (size_t *): Array of sizes for memcpy operations.
  • count (size_t): Size of dsts, srcs and sizes arrays
  • attrs (MUmemcpyAttributes *): Array of memcpy attributes.
  • attrsIdxs (size_t *): Array of indices to specify which copies each entry in the attrs array applies to. The attributes specified in attrs[k] will be applied to copies starting from attrsIdxs[k] through attrsIdxs[k+1] - 1. Also attrs[numAttrs-1] will apply to copies starting from attrsIdxs[numAttrs-1] through count - 1.
  • numAttrs (size_t): Size of attrs and attrsIdxs arrays.
  • failIdx (size_t *): Pointer to a location to return the index of the copy where a failure was encountered. The value will be SIZE_MAX if the error doesn't pertain to any specific copy.
  • hStream (MUstream): The stream to enqueue the operations in. Must not be legacy NULL stream.

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED MUSA_ERROR_NOT_INITIALIZED MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.

muMemoryAtomicBatchAsync​

MUresult muMemoryAtomicBatchAsync(MUdeviceptr *dsts, MUdeviceptr *srcs, size_t *elements, MUatomicType *operation, size_t count, MUmemcpyAttributes *attrs, size_t *attrsIdxs, size_t numAttrs, size_t *failIdx, MUstream hStream)

Description

  • Performs a batch of memory copies asynchronously, and the memory can't be pinned host memory, now just support d2d and p2p.
  • Performs a batch of memory copies. The batch as a whole executes in stream order but copies within a batch are not guaranteed to execute in any specific order. This API only supports pointer-to-pointer copies. For copies involving MUSA arrays, please see muMemcpy3DBatchAsync.
  • Performs memory copies from source buffers specified in srcs to destination buffers specified in dsts. The size of each copy is specified in sizes. All three arrays must be of the same length as specified by count. Since there are no ordering guarantees for copies within a batch, specifying any dependent copies within a batch will result in undefined behavior.
  • Every copy in the batch has to be associated with a set of attributes specified in the attrs array. Each entry in this array can apply to more than one copy. This can be done by specifying in the attrsIdxs array, the index of the first copy that the corresponding entry in the attrs array applies to. Both attrs and attrsIdxs must be of the same length as specified by numAttrs. For example, if a batch has 10 copies listed in dst/src/sizes, the first 6 of which have one set of attributes and the remaining 4 another, then numAttrs will be 2, attrsIdxs will be {0, 6} and attrs will contains the two sets of attributes. Note that the first entry in attrsIdxs must always be 0. Also, each entry must be greater than the previous entry and the last entry should be less than count. Furthermore, numAttrs must be lesser than or equal to count.
  • The MUmemcpyAttributes::srcAccessOrder indicates the source access ordering to be observed for copies associated with the attribute. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_STREAM, then the source will be accessed in stream order. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_DURING_API_CALL then it indicates that access to the source pointer can be out of stream order and all accesses must be complete before the API call returns. This flag is suited for ephemeral sources (ex., stack variables) when it's known that no prior operations in the stream can be accessing the memory and also that the lifetime of the memory is limited to the scope that the source variable was declared in. Specifying this flag allows the driver to optimize the copy and removes the need for the user to synchronize the stream after the API call. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_ANY then it indicates that access to the source pointer can be out of stream order and the accesses can happen even after the API call returns. This flag is suited for host pointers allocated outside MUSA (ex., via malloc) when it's known that no prior operations in the stream can be accessing the memory. Specifying this flag allows the driver to optimize the copy on certain platforms. Each memcpy operation in the batch must have a valid MUmemcpyAttributes corresponding to it including the appropriate srcAccessOrder setting, otherwise the API will return MUSA_ERROR_INVALID_VALUE.
  • The MUmemcpyAttributes::srcLocHint and MUmemcpyAttributes::dstLocHint allows applications to specify hint locations for operands of a copy when the operand doesn't have a fixed location. That is, these hints are only applicable for managed memory pointers on devices where MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS is true or system-allocated pageable memory on devices where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS is true. For other cases, these hints are ignored.
  • The MUmemcpyAttributes::flags field can be used to specify certain flags for copies. Setting the MU_MEMCPY_FLAG_PREFER_OVERLAP_WITH_COMPUTE flag indicates that the associated copies should preferably overlap with any compute work. Note that this flag is a hint and can be ignored depending on the platform and other parameters of the copy.
  • If any error is encountered while parsing the batch, the index within the batch where the error was encountered will be returned in failIdx.

Parameters

  • dsts (MUdeviceptr *): Array of destination pointers.
  • srcs (MUdeviceptr *): Array of memcpy source pointers.
  • elements (size_t *): Array of elements for memcpy operations.
  • operation (MUatomicType *): Array of atomic operations type.
  • count (size_t): Size of dsts, srcs and sizes arrays
  • attrs (MUmemcpyAttributes *): Array of memcpy attributes.
  • attrsIdxs (size_t *): Array of indices to specify which copies each entry in the attrs array applies to. The attributes specified in attrs[k] will be applied to copies starting from attrsIdxs[k] through attrsIdxs[k+1] - 1. Also attrs[numAttrs-1] will apply to copies starting from attrsIdxs[numAttrs-1] through count - 1.
  • numAttrs (size_t): Size of attrs and attrsIdxs arrays.
  • failIdx (size_t *): Pointer to a location to return the index of the copy where a failure was encountered. The value will be SIZE_MAX if the error doesn't pertain to any specific copy.
  • hStream (MUstream): The stream to enqueue the operations in. Must not be legacy NULL stream.

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED MUSA_ERROR_NOT_INITIALIZED MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.

muMemcpy3DBatchAsync​

MUresult muMemcpy3DBatchAsync(size_t numOps, MUSA_MEMCPY3D_BATCH_OP *opList, size_t *failIdx, unsigned long long flags, MUstream hStream)

Description

  • Performs a batch of 3D memory copies asynchronously.
  • Performs a batch of memory copies. The batch as a whole executes in stream order but copies within a batch are not guaranteed to execute in any specific order. Note that this means specifying any dependent copies within a batch will result in undefined behavior.
  • Performs memory copies as specified in the opList array. The length of this array is specified in numOps. Each entry in this array describes a copy operation. This includes among other things, the source and destination operands for the copy as specified in MUSA_MEMCPY3D_BATCH_OP::src and MUSA_MEMCPY3D_BATCH_OP::dst respectively. The source and destination operands of a copy can either be a pointer or a MUSA array. The width, height and depth of a copy is specified in MUSA_MEMCPY3D_BATCH_OP::extent. The width, height and depth of a copy are specified in elements and must not be zero. For pointer-to-pointer copies, the element size is considered to be 1. For pointer to MUSA array or vice versa copies, the element size is determined by the MUSA array. For MUSA array to MUSA array copies, the element size of the two MUSA arrays must match.
  • For a given operand, if MUmemcpy3DOperand::type is specified as MU_MEMCPY_OPERAND_TYPE_POINTER, then MUmemcpy3DOperand::op::ptr will be used. The MUmemcpy3DOperand::op::ptr::ptr field must contain the pointer where the copy should begin. The MUmemcpy3DOperand::op::ptr::rowLength field specifies the length of each row in elements and must either be zero or be greater than or equal to the width of the copy specified in MUSA_MEMCPY3D_BATCH_OP::extent::width. The MUmemcpy3DOperand::op::ptr::layerHeight field specifies the height of each layer and must either be zero or be greater than or equal to the height of the copy specified in MUSA_MEMCPY3D_BATCH_OP::extent::height. When either of these values is zero, that aspect of the operand is considered to be tightly packed according to the copy extent. For managed memory pointers on devices where MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS is true or system-allocated pageable memory on devices where MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS is true, the MUmemcpy3DOperand::op::ptr::locHint field can be used to hint the location of the operand.
  • If an operand's type is specified as MU_MEMCPY_OPERAND_TYPE_ARRAY, then MUmemcpy3DOperand::op::array will be used. The MUmemcpy3DOperand::op::array::array field specifies the MUSA array and MUmemcpy3DOperand::op::array::offset specifies the 3D offset into that array where the copy begins.
  • The MUmemcpyAttributes::srcAccessOrder indicates the source access ordering to be observed for copies associated with the attribute. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_STREAM, then the source will be accessed in stream order. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_DURING_API_CALL then it indicates that access to the source pointer can be out of stream order and all accesses must be complete before the API call returns. This flag is suited for ephemeral sources (ex., stack variables) when it's known that no prior operations in the stream can be accessing the memory and also that the lifetime of the memory is limited to the scope that the source variable was declared in. Specifying this flag allows the driver to optimize the copy and removes the need for the user to synchronize the stream after the API call. If the source access order is set to MU_MEMCPY_SRC_ACCESS_ORDER_ANY then it indicates that access to the source pointer can be out of stream order and the accesses can happen even after the API call returns. This flag is suited for host pointers allocated outside MUSA (ex., via malloc) when it's known that no prior operations in the stream can be accessing the memory. Specifying this flag allows the driver to optimize the copy on certain platforms. Each memcopy operation in opList must have a valid srcAccessOrder setting, otherwise this API will return MUSA_ERROR_INVALID_VALUE.
  • The MUmemcpyAttributes::flags field can be used to specify certain flags for copies. Setting the MU_MEMCPY_FLAG_PREFER_OVERLAP_WITH_COMPUTE flag indicates that the associated copies should preferably overlap with any compute work. Note that this flag is a hint and can be ignored depending on the platform and other parameters of the copy.
  • If any error is encountered while parsing the batch, the index within the batch where the error was encountered will be returned in failIdx.

Parameters

  • numOps (size_t): Total number of memcpy operations.
  • opList (MUSA_MEMCPY3D_BATCH_OP *): Array of size numOps containing the actual memcpy operations.
  • failIdx (size_t *): Pointer to a location to return the index of the copy where a failure was encountered. The value will be SIZE_MAX if the error doesn't pertain to any specific copy.
  • flags (unsigned long long): Flags for future use, must be zero now.
  • hStream (MUstream): The stream to enqueue the operations in. Must not be default NULL stream.

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED MUSA_ERROR_NOT_INITIALIZED MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.

muMemsetD8​

MUresult muMemsetD8(MUdeviceptr dstDevice, unsigned char uc, size_t N)

Description

  • Initializes device memory.
  • Performs asynchronous memory copy operation with the specified attributes.
  • Performs asynchronous memory copy operation where dst and src are the destination and source pointers respectively. size specifies the number of bytes to copy. attr specifies the attributes for the copy and hStream specifies the stream to enqueue the operation in.
  • For more information regarding the attributes, please refer to MUmemcpyAttributes and it's usage desciption in::muMemcpyBatchAsync
  • For more information regarding the operation, please refer to MUSA_MEMCPY3D_BATCH_OP and it's usage desciption in::muMemcpy3DBatchAsync

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • uc (unsigned char): Value to set
  • N (size_t): Number of elements

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD8_v2, muMemsetD8_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memcpy-specific synchronization semantics.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD16​

MUresult muMemsetD16(MUdeviceptr dstDevice, unsigned short us, size_t N)

Description

  • Initializes device memory.
  • Sets the memory range of N 16-bit values to the specified value us. The dstDevice pointer must be two byte aligned.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • us (unsigned short): Value to set
  • N (size_t): Number of elements

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD16_v2, muMemsetD16_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD32​

MUresult muMemsetD32(MUdeviceptr dstDevice, unsigned int ui, size_t N)

Description

  • Initializes device memory.
  • Sets the memory range of N 32-bit values to the specified value ui. The dstDevice pointer must be four byte aligned.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • ui (unsigned int): Value to set
  • N (size_t): Number of elements

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD32_v2, muMemsetD32_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD2D8​

MUresult muMemsetD2D8(MUdeviceptr dstDevice, size_t dstPitch, unsigned char uc, size_t Width, size_t Height)

Description

  • Initializes device memory.
  • Sets the 2D memory range of Width 8-bit values to the specified value uc. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • uc (unsigned char): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D8_v2, muMemsetD2D8_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD2D16​

MUresult muMemsetD2D16(MUdeviceptr dstDevice, size_t dstPitch, unsigned short us, size_t Width, size_t Height)

Description

  • Initializes device memory.
  • Sets the 2D memory range of Width 16-bit values to the specified value us. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. The dstDevice pointer and dstPitch offset must be two byte aligned. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • us (unsigned short): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D16_v2, muMemsetD2D16_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD2D32​

MUresult muMemsetD2D32(MUdeviceptr dstDevice, size_t dstPitch, unsigned int ui, size_t Width, size_t Height)

Description

  • Initializes device memory.
  • Sets the 2D memory range of Width 32-bit values to the specified value ui. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. The dstDevice pointer and dstPitch offset must be four byte aligned. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • ui (unsigned int): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D32_v2, muMemsetD2D32_v2_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.

See also

muMemsetD8Async​

MUresult muMemsetD8Async(MUdeviceptr dstDevice, unsigned char uc, size_t N, MUstream hStream)

Description

  • Sets device memory.
  • Sets the memory range of N 8-bit values to the specified value uc.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • uc (unsigned char): Value to set
  • N (size_t): Number of elements
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD8Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muMemsetD16Async​

MUresult muMemsetD16Async(MUdeviceptr dstDevice, unsigned short us, size_t N, MUstream hStream)

Description

  • Sets device memory.
  • Sets the memory range of N 16-bit values to the specified value us. The dstDevice pointer must be two byte aligned.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • us (unsigned short): Value to set
  • N (size_t): Number of elements
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD16Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muMemsetD32Async​

MUresult muMemsetD32Async(MUdeviceptr dstDevice, unsigned int ui, size_t N, MUstream hStream)

Description

  • Sets device memory.
  • Sets the memory range of N 32-bit values to the specified value ui. The dstDevice pointer must be four byte aligned.

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • ui (unsigned int): Value to set
  • N (size_t): Number of elements
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD32Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muMemsetD2D8Async​

MUresult muMemsetD2D8Async(MUdeviceptr dstDevice, size_t dstPitch, unsigned char uc, size_t Width, size_t Height, MUstream hStream)

Description

  • Sets device memory.
  • Sets the 2D memory range of Width 8-bit values to the specified value uc. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • uc (unsigned char): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D8Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muMemsetD2D16Async​

MUresult muMemsetD2D16Async(MUdeviceptr dstDevice, size_t dstPitch, unsigned short us, size_t Width, size_t Height, MUstream hStream)

Description

  • Sets device memory.
  • Sets the 2D memory range of Width 16-bit values to the specified value us. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. The dstDevice pointer and dstPitch offset must be two byte aligned. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • us (unsigned short): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D16Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muMemsetD2D32Async​

MUresult muMemsetD2D32Async(MUdeviceptr dstDevice, size_t dstPitch, unsigned int ui, size_t Width, size_t Height, MUstream hStream)

Description

  • Sets device memory.
  • Sets the 2D memory range of Width 32-bit values to the specified value ui. Height specifies the number of rows to set, and dstPitch specifies the number of bytes between each row. The dstDevice pointer and dstPitch offset must be four byte aligned. This function performs fastest when the pitch is one that has been passed back by muMemAllocPitch().

Parameters

  • dstDevice (MUdeviceptr): Destination device pointer
  • dstPitch (size_t): Pitch of destination device pointer(Unused if Height is 1)
  • ui (unsigned int): Value to set
  • Width (size_t): Width of row
  • Height (size_t): Number of rows
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemsetD2D32Async_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for memset-specific synchronization semantics.
  • See the default-stream note for NULL stream semantics.

See also

muArrayCreate​

MUresult muArrayCreate(MUarray *pHandle, const MUSA_ARRAY_DESCRIPTOR *pAllocateArray)

Description

  • Creates a 1D or 2D MUSA array.
  • Creates a MUSA array according to the MUSA_ARRAY_DESCRIPTOR structure pAllocateArray and returns a handle to the new MUSA array in *pHandle. The MUSA_ARRAY_DESCRIPTOR is defined as:
typedef struct  {
  unsigned int Width;
  unsigned int Height;
  MUarray_format Format;
  unsigned int NumChannels;
} MUSA_ARRAY_DESCRIPTOR;
  • where:
  • Width, and Height are the width, and height of the MUSA array (in elements); the MUSA array is one-dimensional if height is 0, two-dimensional otherwise; Format specifies the format of the elements; MUarray_format is defined as:
typedef enum MUarray_format_enum {
  MU_AD_FORMAT_UNSIGNED_INT8 = 0x01,
  MU_AD_FORMAT_UNSIGNED_INT16 = 0x02,
  MU_AD_FORMAT_UNSIGNED_INT32 = 0x03,
  MU_AD_FORMAT_SIGNED_INT8 = 0x08,
  MU_AD_FORMAT_SIGNED_INT16 = 0x09,
  MU_AD_FORMAT_SIGNED_INT32 = 0x0a,
  MU_AD_FORMAT_HALF = 0x10,
  MU_AD_FORMAT_FLOAT = 0x20,
  MU_AD_FORMAT_NV12 = 0xb0,
  MU_AD_FORMAT_UNORM_INT8X1 = 0xc0,
  MU_AD_FORMAT_UNORM_INT8X2 = 0xc1,
  MU_AD_FORMAT_UNORM_INT8X4 = 0xc2,
  MU_AD_FORMAT_UNORM_INT16X1 = 0xc3,
  MU_AD_FORMAT_UNORM_INT16X2 = 0xc4,
  MU_AD_FORMAT_UNORM_INT16X4 = 0xc5,
  MU_AD_FORMAT_SNORM_INT8X1 = 0xc6,
  MU_AD_FORMAT_SNORM_INT8X2 = 0xc7,
  MU_AD_FORMAT_SNORM_INT8X4 = 0xc8,
  MU_AD_FORMAT_SNORM_INT16X1 = 0xc9,
  MU_AD_FORMAT_SNORM_INT16X2 = 0xca,
  MU_AD_FORMAT_SNORM_INT16X4 = 0xcb,
  MU_AD_FORMAT_BC1_UNORM = 0x91,
  MU_AD_FORMAT_BC1_UNORM_SRGB = 0x92,
  MU_AD_FORMAT_BC2_UNORM = 0x93,
  MU_AD_FORMAT_BC2_UNORM_SRGB = 0x94,
  MU_AD_FORMAT_BC3_UNORM = 0x95,
  MU_AD_FORMAT_BC3_UNORM_SRGB = 0x96,
  MU_AD_FORMAT_BC4_UNORM = 0x97,
  MU_AD_FORMAT_BC4_SNORM = 0x98,
  MU_AD_FORMAT_BC5_UNORM = 0x99,
  MU_AD_FORMAT_BC5_SNORM = 0x9a,
  MU_AD_FORMAT_BC6H_UF16 = 0x9b,
  MU_AD_FORMAT_BC6H_SF16 = 0x9c,
  MU_AD_FORMAT_BC7_UNORM = 0x9d,
  MU_AD_FORMAT_BC7_UNORM_SRGB = 0x9e,
  MU_AD_FORMAT_P010 = 0x9f,
  MU_AD_FORMAT_P016 = 0xa1,
  MU_AD_FORMAT_NV16 = 0xa2,
  MU_AD_FORMAT_P210 = 0xa3,
  MU_AD_FORMAT_P216 = 0xa4,
  MU_AD_FORMAT_YUY2 = 0xa5,
  MU_AD_FORMAT_Y210 = 0xa6,
  MU_AD_FORMAT_Y216 = 0xa7,
  MU_AD_FORMAT_AYUV = 0xa8,
  MU_AD_FORMAT_Y410 = 0xa9,
  MU_AD_FORMAT_Y416 = 0xb1,
  MU_AD_FORMAT_Y444_PLANAR8 = 0xb2,
  MU_AD_FORMAT_Y444_PLANAR10 = 0xb3,
  MU_AD_FORMAT_YUV444_8bit_SemiPlanar = 0xb4,
  MU_AD_FORMAT_YUV444_16bit_SemiPlanar = 0xb5,
  MU_AD_FORMAT_UNORM_INT_101010_2 = 0x50,
  MU_AD_FORMAT_UINT8_PACKED_422 = 0x51,
  MU_AD_FORMAT_UINT8_PACKED_444 = 0x52,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_420 = 0x53,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_420 = 0x54,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_422 = 0x55,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_422 = 0x56,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_444 = 0x57,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_444 = 0x58,
  MU_AD_FORMAT_UINT8_PLANAR_420 = 0x59,
  MU_AD_FORMAT_UINT16_PLANAR_420 = 0x5a,
  MU_AD_FORMAT_UINT8_PLANAR_422 = 0x5b,
  MU_AD_FORMAT_UINT16_PLANAR_422 = 0x5c,
  MU_AD_FORMAT_UINT8_PLANAR_444 = 0x5d,
  MU_AD_FORMAT_UINT16_PLANAR_444 = 0x5e,
} MUarray_format;
  • NumChannels specifies the number of packed components per MUSA array element; it may be 1, 2, or 4;
  • Here are examples of MUSA array descriptions:
  • Description for a MUSA array of 2048 floats: MUSA_ARRAY_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_FLOAT; desc.NumChannels=1; desc.Width=2048; desc.Height=1;
  • Description for a 64 x 64 MUSA array of floats: MUSA_ARRAY_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_FLOAT; desc.NumChannels=1; desc.Width=64; desc.Height=64;
  • Description for a width x height MUSA array of 64-bit, 4x16-bit float16's: MUSA_ARRAY_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_HALF; desc.NumChannels=4; desc.Width=width; desc.Height=height;
  • Description for a width x height MUSA array of 16-bit elements, each of which is two 8-bit unsigned chars: MUSA_ARRAY_DESCRIPTORarrayDesc; desc.Format=MU_AD_FORMAT_UNSIGNED_INT8; desc.NumChannels=2; desc.Width=width; desc.Height=height;

Parameters

  • pHandle (MUarray *): Returned array
  • pAllocateArray (const MUSA_ARRAY_DESCRIPTOR *): Array descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN

Note

  • Additional exported symbol names in scope: muArrayCreate_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muArrayGetDescriptor​

MUresult muArrayGetDescriptor(MUSA_ARRAY_DESCRIPTOR *pArrayDescriptor, MUarray hArray)

Description

  • Get a 1D or 2D MUSA array descriptor.
  • Returns in *pArrayDescriptor a descriptor containing information on the format and dimensions of the MUSA array hArray. It is useful for subroutines that have been passed a MUSA array, but need to know the MUSA array parameters for validation or other purposes.

Parameters

  • pArrayDescriptor (MUSA_ARRAY_DESCRIPTOR *): Returned array descriptor
  • hArray (MUarray): Array to get descriptor of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muArrayGetDescriptor_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muArrayGetMemoryRequirements​

MUresult muArrayGetMemoryRequirements(MUSA_ARRAY_MEMORY_REQUIREMENTS *memoryRequirements, MUarray array, MUdevice device)

Description

  • Returns the layout properties of a sparse MUSA array.
  • Returns the layout properties of a sparse MUSA array in sparseProperties If the MUSA array is not allocated with flag MUSA_ARRAY3D_SPARSE MUSA_ERROR_INVALID_VALUE will be returned.
  • If the returned value in MUSA_ARRAY_SPARSE_PROPERTIES::flags contains MU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL, then MUSA_ARRAY_SPARSE_PROPERTIES::miptailSize represents the total size of the array. Otherwise, it will be zero. Also, the returned value in MUSA_ARRAY_SPARSE_PROPERTIES::miptailFirstLevel is always zero. Note that the array must have been allocated using muArrayCreate or muArray3DCreate. For MUSA arrays obtained using muMipmappedArrayGetLevel, MUSA_ERROR_INVALID_VALUE will be returned. Instead, muMipmappedArrayGetSparseProperties must be used to obtain the sparse properties of the entire MUSA mipmapped array to which array belongs to.
  • Returns the sparse array layout properties in sparseProperties If the MUSA mipmapped array is not allocated with flag MUSA_ARRAY3D_SPARSE MUSA_ERROR_INVALID_VALUE will be returned.
  • For non-layered MUSA mipmapped arrays, MUSA_ARRAY_SPARSE_PROPERTIES::miptailSize returns the size of the mip tail region. The mip tail region includes all mip levels whose width, height or depth is less than that of the tile. For layered MUSA mipmapped arrays, if MUSA_ARRAY_SPARSE_PROPERTIES::flags contains MU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL, then MUSA_ARRAY_SPARSE_PROPERTIES::miptailSize specifies the size of the mip tail of all layers combined. Otherwise, MUSA_ARRAY_SPARSE_PROPERTIES::miptailSize specifies mip tail size per layer. The returned value of MUSA_ARRAY_SPARSE_PROPERTIES::miptailFirstLevel is valid only if MUSA_ARRAY_SPARSE_PROPERTIES::miptailSize is non-zero.
  • Returns the memory requirements of a MUSA array in memoryRequirements If the MUSA array is not allocated with flag MUSA_ARRAY3D_DEFERRED_MAPPING MUSA_ERROR_INVALID_VALUE will be returned.
  • The returned value in MUSA_ARRAY_MEMORY_REQUIREMENTS::size represents the total size of the MUSA array. The returned value in MUSA_ARRAY_MEMORY_REQUIREMENTS::alignment represents the alignment necessary for mapping the MUSA array.

Parameters

  • memoryRequirements (MUSA_ARRAY_MEMORY_REQUIREMENTS *): Pointer to MUSA_ARRAY_MEMORY_REQUIREMENTS
  • array (MUarray): MUSA array to get the memory requirements of
  • device (MUdevice): Device to get the memory requirements for

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

See also

muMipmappedArrayGetMemoryRequirements​

MUresult muMipmappedArrayGetMemoryRequirements(MUSA_ARRAY_MEMORY_REQUIREMENTS *memoryRequirements, MUmipmappedArray mipmap, MUdevice device)

Description

  • Returns the memory requirements of a MUSA mipmapped array.
  • Returns the memory requirements of a MUSA mipmapped array in memoryRequirements If the MUSA mipmapped array is not allocated with flag MUSA_ARRAY3D_DEFERRED_MAPPING MUSA_ERROR_INVALID_VALUE will be returned.
  • The returned value in MUSA_ARRAY_MEMORY_REQUIREMENTS::size represents the total size of the MUSA mipmapped array. The returned value in MUSA_ARRAY_MEMORY_REQUIREMENTS::alignment represents the alignment necessary for mapping the MUSA mipmapped array.

Parameters

  • memoryRequirements (MUSA_ARRAY_MEMORY_REQUIREMENTS *): Pointer to MUSA_ARRAY_MEMORY_REQUIREMENTS
  • mipmap (MUmipmappedArray): MUSA mipmapped array to get the memory requirements of
  • device (MUdevice): Device to get the memory requirements for

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

See also

muArrayDestroy​

MUresult muArrayDestroy(MUarray hArray)

Description

  • Gets a MUSA array plane from a MUSA array.
  • Returns in pPlaneArray a MUSA array that represents a single format plane of the MUSA array hArray.
  • If planeIdx is greater than the maximum number of planes in this array or if the array does not have a multi-planar format e.g: MU_AD_FORMAT_NV12, then MUSA_ERROR_INVALID_VALUE is returned.
  • Note that if the hArray has format MU_AD_FORMAT_NV12, then passing in 0 for planeIdx returns a MUSA array of the same size as hArray but with one channel and MU_AD_FORMAT_UNSIGNED_INT8 as its format. If 1 is passed for planeIdx, then the returned MUSA array has half the height and width of hArray with two channels and MU_AD_FORMAT_UNSIGNED_INT8 as its format.
  • Destroys the MUSA array hArray.

Parameters

  • hArray (MUarray): Array to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ARRAY_IS_MAPPED, MUSA_ERROR_CONTEXT_IS_DESTROYED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muArray3DCreate​

MUresult muArray3DCreate(MUarray *pHandle, const MUSA_ARRAY3D_DESCRIPTOR *pAllocateArray)

Description

  • Creates a 3D MUSA array.
  • Creates a MUSA array according to the MUSA_ARRAY3D_DESCRIPTOR structure pAllocateArray and returns a handle to the new MUSA array in *pHandle. The MUSA_ARRAY3D_DESCRIPTOR is defined as:
typedef struct  {
  unsigned int Width;
  unsigned int Height;
  unsigned int Depth;
  MUarray_format Format;
  unsigned int NumChannels;
  unsigned int Flags;
} MUSA_ARRAY3D_DESCRIPTOR;
  • where:
  • Width, Height, and Depth are the width, height, and depth of the MUSA array (in elements); the following types of MUSA arrays can be allocated: A 1D array is allocated if Height and Depth extents are both zero. A 2D array is allocated if only Depth extent is zero. A 3D array is allocated if all three extents are non-zero. A 1D layered MUSA array is allocated if only Height is zero and the MUSA_ARRAY3D_LAYERED flag is set. Each layer is a 1D array. The number of layers is determined by the depth extent. A 2D layered MUSA array is allocated if all three extents are non-zero and the MUSA_ARRAY3D_LAYERED flag is set. Each layer is a 2D array. The number of layers is determined by the depth extent. A cubemap MUSA array is allocated if all three extents are non-zero and the MUSA_ARRAY3D_CUBEMAP flag is set. Width must be equal to Height, and Depth must be six. A cubemap is a special type of 2D layered MUSA array, where the six layers represent the six faces of a cube. The order of the six layers in memory is the same as that listed in MUarray_cubemap_face. A cubemap layered MUSA array is allocated if all three extents are non-zero, and both, MUSA_ARRAY3D_CUBEMAP and MUSA_ARRAY3D_LAYERED flags are set. Width must be equal to Height, and Depth must be a multiple of six. A cubemap layered MUSA array is a special type of 2D layered MUSA array that consists of a collection of cubemaps. The first six layers represent the first cubemap, the next six layers form the second cubemap, and so on. Format specifies the format of the elements; MUarray_format is defined as:
typedef enum MUarray_format_enum {
  MU_AD_FORMAT_UNSIGNED_INT8 = 0x01,
  MU_AD_FORMAT_UNSIGNED_INT16 = 0x02,
  MU_AD_FORMAT_UNSIGNED_INT32 = 0x03,
  MU_AD_FORMAT_SIGNED_INT8 = 0x08,
  MU_AD_FORMAT_SIGNED_INT16 = 0x09,
  MU_AD_FORMAT_SIGNED_INT32 = 0x0a,
  MU_AD_FORMAT_HALF = 0x10,
  MU_AD_FORMAT_FLOAT = 0x20,
  MU_AD_FORMAT_NV12 = 0xb0,
  MU_AD_FORMAT_UNORM_INT8X1 = 0xc0,
  MU_AD_FORMAT_UNORM_INT8X2 = 0xc1,
  MU_AD_FORMAT_UNORM_INT8X4 = 0xc2,
  MU_AD_FORMAT_UNORM_INT16X1 = 0xc3,
  MU_AD_FORMAT_UNORM_INT16X2 = 0xc4,
  MU_AD_FORMAT_UNORM_INT16X4 = 0xc5,
  MU_AD_FORMAT_SNORM_INT8X1 = 0xc6,
  MU_AD_FORMAT_SNORM_INT8X2 = 0xc7,
  MU_AD_FORMAT_SNORM_INT8X4 = 0xc8,
  MU_AD_FORMAT_SNORM_INT16X1 = 0xc9,
  MU_AD_FORMAT_SNORM_INT16X2 = 0xca,
  MU_AD_FORMAT_SNORM_INT16X4 = 0xcb,
  MU_AD_FORMAT_BC1_UNORM = 0x91,
  MU_AD_FORMAT_BC1_UNORM_SRGB = 0x92,
  MU_AD_FORMAT_BC2_UNORM = 0x93,
  MU_AD_FORMAT_BC2_UNORM_SRGB = 0x94,
  MU_AD_FORMAT_BC3_UNORM = 0x95,
  MU_AD_FORMAT_BC3_UNORM_SRGB = 0x96,
  MU_AD_FORMAT_BC4_UNORM = 0x97,
  MU_AD_FORMAT_BC4_SNORM = 0x98,
  MU_AD_FORMAT_BC5_UNORM = 0x99,
  MU_AD_FORMAT_BC5_SNORM = 0x9a,
  MU_AD_FORMAT_BC6H_UF16 = 0x9b,
  MU_AD_FORMAT_BC6H_SF16 = 0x9c,
  MU_AD_FORMAT_BC7_UNORM = 0x9d,
  MU_AD_FORMAT_BC7_UNORM_SRGB = 0x9e,
  MU_AD_FORMAT_P010 = 0x9f,
  MU_AD_FORMAT_P016 = 0xa1,
  MU_AD_FORMAT_NV16 = 0xa2,
  MU_AD_FORMAT_P210 = 0xa3,
  MU_AD_FORMAT_P216 = 0xa4,
  MU_AD_FORMAT_YUY2 = 0xa5,
  MU_AD_FORMAT_Y210 = 0xa6,
  MU_AD_FORMAT_Y216 = 0xa7,
  MU_AD_FORMAT_AYUV = 0xa8,
  MU_AD_FORMAT_Y410 = 0xa9,
  MU_AD_FORMAT_Y416 = 0xb1,
  MU_AD_FORMAT_Y444_PLANAR8 = 0xb2,
  MU_AD_FORMAT_Y444_PLANAR10 = 0xb3,
  MU_AD_FORMAT_YUV444_8bit_SemiPlanar = 0xb4,
  MU_AD_FORMAT_YUV444_16bit_SemiPlanar = 0xb5,
  MU_AD_FORMAT_UNORM_INT_101010_2 = 0x50,
} MUarray_format;
  • NumChannels specifies the number of packed components per MUSA array element; it may be 1, 2, or 4; Flags may be set to MUSA_ARRAY3D_LAYERED to enable creation of layered MUSA arrays. If this flag is set, Depth specifies the number of layers, not the depth of a 3D array. MUSA_ARRAY3D_SURFACE_LDST to enable surface references to be bound to the MUSA array. If this flag is not set, muSurfRefSetArray will fail when attempting to bind the MUSA array to a surface reference. MUSA_ARRAY3D_CUBEMAP to enable creation of cubemaps. If this flag is set, Width must be equal to Height, and Depth must be six. If the MUSA_ARRAY3D_LAYERED flag is also set, then Depth must be a multiple of six. MUSA_ARRAY3D_TEXTURE_GATHER to indicate that the MUSA array will be used for texture gather. Texture gather can only be performed on 2D MUSA arrays.
  • Width, Height and Depth must meet certain size requirements as listed in the following table. All values are specified in elements. Note that for brevity's sake, the full name of the device attribute is not specified. For ex., TEXTURE1D_WIDTH refers to the device attribute MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_WIDTH.
  • Note that 2D MUSA arrays have different size requirements if the MUSA_ARRAY3D_TEXTURE_GATHER flag is set. Width and Height must not be greater than MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_GATHER_WIDTH and MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_GATHER_HEIGHT respectively, in that case.
  • MUSA array type Valid extents that must always be met {(width range in elements), (height range), (depth range)} Valid extents with MUSA_ARRAY3D_SURFACE_LDST set {(width range in elements), (height range), (depth range)} 1D { (1,TEXTURE1D_WIDTH), 0, 0 } { (1,SURFACE1D_WIDTH), 0, 0 } 2D { (1,TEXTURE2D_WIDTH), (1,TEXTURE2D_HEIGHT), 0 } { (1,SURFACE2D_WIDTH), (1,SURFACE2D_HEIGHT), 0 } 3D { (1,TEXTURE3D_WIDTH), (1,TEXTURE3D_HEIGHT), (1,TEXTURE3D_DEPTH) } OR { (1,TEXTURE3D_WIDTH_ALTERNATE), (1,TEXTURE3D_HEIGHT_ALTERNATE), (1,TEXTURE3D_DEPTH_ALTERNATE) } { (1,SURFACE3D_WIDTH), (1,SURFACE3D_HEIGHT), (1,SURFACE3D_DEPTH) } 1D Layered { (1,TEXTURE1D_LAYERED_WIDTH), 0, (1,TEXTURE1D_LAYERED_LAYERS) } { (1,SURFACE1D_LAYERED_WIDTH), 0, (1,SURFACE1D_LAYERED_LAYERS) } 2D Layered { (1,TEXTURE2D_LAYERED_WIDTH), (1,TEXTURE2D_LAYERED_HEIGHT), (1,TEXTURE2D_LAYERED_LAYERS) } { (1,SURFACE2D_LAYERED_WIDTH), (1,SURFACE2D_LAYERED_HEIGHT), (1,SURFACE2D_LAYERED_LAYERS) } Cubemap { (1,TEXTURECUBEMAP_WIDTH), (1,TEXTURECUBEMAP_WIDTH), 6 } { (1,SURFACECUBEMAP_WIDTH), (1,SURFACECUBEMAP_WIDTH), 6 } Cubemap Layered { (1,TEXTURECUBEMAP_LAYERED_WIDTH), (1,TEXTURECUBEMAP_LAYERED_WIDTH), (1,TEXTURECUBEMAP_LAYERED_LAYERS) } { (1,SURFACECUBEMAP_LAYERED_WIDTH), (1,SURFACECUBEMAP_LAYERED_WIDTH), (1,SURFACECUBEMAP_LAYERED_LAYERS) }
  • Here are examples of MUSA array descriptions:
  • Description for a MUSA array of 2048 floats: MUSA_ARRAY3D_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_FLOAT; desc.NumChannels=1; desc.Width=2048; desc.Height=0; desc.Depth=0;
  • Description for a 64 x 64 MUSA array of floats: MUSA_ARRAY3D_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_FLOAT; desc.NumChannels=1; desc.Width=64; desc.Height=64; desc.Depth=0;
  • Description for a width x height x depth MUSA array of 64-bit, 4x16-bit float16's: MUSA_ARRAY3D_DESCRIPTORdesc; desc.Format=MU_AD_FORMAT_HALF; desc.NumChannels=4; desc.Width=width; desc.Height=height; desc.Depth=depth;

Parameters

  • pHandle (MUarray *): Returned array
  • pAllocateArray (const MUSA_ARRAY3D_DESCRIPTOR *): 3D array descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN

Note

  • Additional exported symbol names in scope: muArray3DCreate_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muArray3DGetDescriptor​

MUresult muArray3DGetDescriptor(MUSA_ARRAY3D_DESCRIPTOR *pArrayDescriptor, MUarray hArray)

Description

  • Get a 3D MUSA array descriptor.
  • Returns in *pArrayDescriptor a descriptor containing information on the format and dimensions of the MUSA array hArray. It is useful for subroutines that have been passed a MUSA array, but need to know the MUSA array parameters for validation or other purposes.
  • This function may be called on 1D and 2D arrays, in which case the Height and/or Depth members of the descriptor struct will be set to 0.

Parameters

  • pArrayDescriptor (MUSA_ARRAY3D_DESCRIPTOR *): Returned 3D array descriptor
  • hArray (MUarray): 3D array to get descriptor of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_CONTEXT_IS_DESTROYED

Note

  • Additional exported symbol names in scope: muArray3DGetDescriptor_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMipmappedArrayCreate​

MUresult muMipmappedArrayCreate(MUmipmappedArray *pHandle, const MUSA_ARRAY3D_DESCRIPTOR *pMipmappedArrayDesc, unsigned int numMipmapLevels)

Description

  • Creates a MUSA mipmapped array.
  • Creates a MUSA mipmapped array according to the MUSA_ARRAY3D_DESCRIPTOR structure pMipmappedArrayDesc and returns a handle to the new MUSA mipmapped array in *pHandle. numMipmapLevels specifies the number of mipmap levels to be allocated. This value is clamped to the range [1, 1 + floor(log2(max(width, height, depth)))].
  • The MUSA_ARRAY3D_DESCRIPTOR is defined as:
typedef struct  {
  unsigned int Width;
  unsigned int Height;
  unsigned int Depth;
  MUarray_format Format;
  unsigned int NumChannels;
  unsigned int Flags;
} MUSA_ARRAY3D_DESCRIPTOR;
  • where:
  • Width, Height, and Depth are the width, height, and depth of the MUSA array (in elements); the following types of MUSA arrays can be allocated: A 1D mipmapped array is allocated if Height and Depth extents are both zero. A 2D mipmapped array is allocated if only Depth extent is zero. A 3D mipmapped array is allocated if all three extents are non-zero. A 1D layered MUSA mipmapped array is allocated if only Height is zero and the MUSA_ARRAY3D_LAYERED flag is set. Each layer is a 1D array. The number of layers is determined by the depth extent. A 2D layered MUSA mipmapped array is allocated if all three extents are non-zero and the MUSA_ARRAY3D_LAYERED flag is set. Each layer is a 2D array. The number of layers is determined by the depth extent. A cubemap MUSA mipmapped array is allocated if all three extents are non-zero and the MUSA_ARRAY3D_CUBEMAP flag is set. Width must be equal to Height, and Depth must be six. A cubemap is a special type of 2D layered MUSA array, where the six layers represent the six faces of a cube. The order of the six layers in memory is the same as that listed in MUarray_cubemap_face. A cubemap layered MUSA mipmapped array is allocated if all three extents are non-zero, and both, MUSA_ARRAY3D_CUBEMAP and MUSA_ARRAY3D_LAYERED flags are set. Width must be equal to Height, and Depth must be a multiple of six. A cubemap layered MUSA array is a special type of 2D layered MUSA array that consists of a collection of cubemaps. The first six layers represent the first cubemap, the next six layers form the second cubemap, and so on. Format specifies the format of the elements; MUarray_format is defined as:
typedef enum MUarray_format_enum {
  MU_AD_FORMAT_UNSIGNED_INT8 = 0x01,
  MU_AD_FORMAT_UNSIGNED_INT16 = 0x02,
  MU_AD_FORMAT_UNSIGNED_INT32 = 0x03,
  MU_AD_FORMAT_SIGNED_INT8 = 0x08,
  MU_AD_FORMAT_SIGNED_INT16 = 0x09,
  MU_AD_FORMAT_SIGNED_INT32 = 0x0a,
  MU_AD_FORMAT_HALF = 0x10,
  MU_AD_FORMAT_FLOAT = 0x20,
  MU_AD_FORMAT_NV12 = 0xb0,
  MU_AD_FORMAT_UNORM_INT8X1 = 0xc0,
  MU_AD_FORMAT_UNORM_INT8X2 = 0xc1,
  MU_AD_FORMAT_UNORM_INT8X4 = 0xc2,
  MU_AD_FORMAT_UNORM_INT16X1 = 0xc3,
  MU_AD_FORMAT_UNORM_INT16X2 = 0xc4,
  MU_AD_FORMAT_UNORM_INT16X4 = 0xc5,
  MU_AD_FORMAT_SNORM_INT8X1 = 0xc6,
  MU_AD_FORMAT_SNORM_INT8X2 = 0xc7,
  MU_AD_FORMAT_SNORM_INT8X4 = 0xc8,
  MU_AD_FORMAT_SNORM_INT16X1 = 0xc9,
  MU_AD_FORMAT_SNORM_INT16X2 = 0xca,
  MU_AD_FORMAT_SNORM_INT16X4 = 0xcb,
  MU_AD_FORMAT_BC1_UNORM = 0x91,
  MU_AD_FORMAT_BC1_UNORM_SRGB = 0x92,
  MU_AD_FORMAT_BC2_UNORM = 0x93,
  MU_AD_FORMAT_BC2_UNORM_SRGB = 0x94,
  MU_AD_FORMAT_BC3_UNORM = 0x95,
  MU_AD_FORMAT_BC3_UNORM_SRGB = 0x96,
  MU_AD_FORMAT_BC4_UNORM = 0x97,
  MU_AD_FORMAT_BC4_SNORM = 0x98,
  MU_AD_FORMAT_BC5_UNORM = 0x99,
  MU_AD_FORMAT_BC5_SNORM = 0x9a,
  MU_AD_FORMAT_BC6H_UF16 = 0x9b,
  MU_AD_FORMAT_BC6H_SF16 = 0x9c,
  MU_AD_FORMAT_BC7_UNORM = 0x9d,
  MU_AD_FORMAT_BC7_UNORM_SRGB = 0x9e,
  MU_AD_FORMAT_P010 = 0x9f,
  MU_AD_FORMAT_P016 = 0xa1,
  MU_AD_FORMAT_NV16 = 0xa2,
  MU_AD_FORMAT_P210 = 0xa3,
  MU_AD_FORMAT_P216 = 0xa4,
  MU_AD_FORMAT_YUY2 = 0xa5,
  MU_AD_FORMAT_Y210 = 0xa6,
  MU_AD_FORMAT_Y216 = 0xa7,
  MU_AD_FORMAT_AYUV = 0xa8,
  MU_AD_FORMAT_Y410 = 0xa9,
  MU_AD_FORMAT_Y416 = 0xb1,
  MU_AD_FORMAT_Y444_PLANAR8 = 0xb2,
  MU_AD_FORMAT_Y444_PLANAR10 = 0xb3,
  MU_AD_FORMAT_YUV444_8bit_SemiPlanar = 0xb4,
  MU_AD_FORMAT_YUV444_16bit_SemiPlanar = 0xb5,
  MU_AD_FORMAT_UNORM_INT_101010_2 = 0x50,
  MU_AD_FORMAT_UINT8_PACKED_422 = 0x51,
  MU_AD_FORMAT_UINT8_PACKED_444 = 0x52,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_420 = 0x53,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_420 = 0x54,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_422 = 0x55,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_422 = 0x56,
  MU_AD_FORMAT_UINT8_SEMIPLANAR_444 = 0x57,
  MU_AD_FORMAT_UINT16_SEMIPLANAR_444 = 0x58,
  MU_AD_FORMAT_UINT8_PLANAR_420 = 0x59,
  MU_AD_FORMAT_UINT16_PLANAR_420 = 0x5a,
  MU_AD_FORMAT_UINT8_PLANAR_422 = 0x5b,
  MU_AD_FORMAT_UINT16_PLANAR_422 = 0x5c,
  MU_AD_FORMAT_UINT8_PLANAR_444 = 0x5d,
  MU_AD_FORMAT_UINT16_PLANAR_444 = 0x5e,
} MUarray_format;
  • NumChannels specifies the number of packed components per MUSA array element; it may be 1, 2, or 4; Flags may be set to MUSA_ARRAY3D_LAYERED to enable creation of layered MUSA mipmapped arrays. If this flag is set, Depth specifies the number of layers, not the depth of a 3D array. MUSA_ARRAY3D_SURFACE_LDST to enable surface references to be bound to individual mipmap levels of the MUSA mipmapped array. If this flag is not set, muSurfRefSetArray will fail when attempting to bind a mipmap level of the MUSA mipmapped array to a surface reference. MUSA_ARRAY3D_CUBEMAP to enable creation of mipmapped cubemaps. If this flag is set, Width must be equal to Height, and Depth must be six. If the MUSA_ARRAY3D_LAYERED flag is also set, then Depth must be a multiple of six. MUSA_ARRAY3D_TEXTURE_GATHER to indicate that the MUSA mipmapped array will be used for texture gather. Texture gather can only be performed on 2D MUSA mipmapped arrays.
  • Width, Height and Depth must meet certain size requirements as listed in the following table. All values are specified in elements. Note that for brevity's sake, the full name of the device attribute is not specified. For ex., TEXTURE1D_MIPMAPPED_WIDTH refers to the device attribute MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_MIPMAPPED_WIDTH.
  • MUSA array type Valid extents that must always be met {(width range in elements), (height range), (depth range)} Valid extents with MUSA_ARRAY3D_SURFACE_LDST set {(width range in elements), (height range), (depth range)} 1D { (1,TEXTURE1D_MIPMAPPED_WIDTH), 0, 0 } { (1,SURFACE1D_WIDTH), 0, 0 } 2D { (1,TEXTURE2D_MIPMAPPED_WIDTH), (1,TEXTURE2D_MIPMAPPED_HEIGHT), 0 } { (1,SURFACE2D_WIDTH), (1,SURFACE2D_HEIGHT), 0 } 3D { (1,TEXTURE3D_WIDTH), (1,TEXTURE3D_HEIGHT), (1,TEXTURE3D_DEPTH) } OR { (1,TEXTURE3D_WIDTH_ALTERNATE), (1,TEXTURE3D_HEIGHT_ALTERNATE), (1,TEXTURE3D_DEPTH_ALTERNATE) } { (1,SURFACE3D_WIDTH), (1,SURFACE3D_HEIGHT), (1,SURFACE3D_DEPTH) } 1D Layered { (1,TEXTURE1D_LAYERED_WIDTH), 0, (1,TEXTURE1D_LAYERED_LAYERS) } { (1,SURFACE1D_LAYERED_WIDTH), 0, (1,SURFACE1D_LAYERED_LAYERS) } 2D Layered { (1,TEXTURE2D_LAYERED_WIDTH), (1,TEXTURE2D_LAYERED_HEIGHT), (1,TEXTURE2D_LAYERED_LAYERS) } { (1,SURFACE2D_LAYERED_WIDTH), (1,SURFACE2D_LAYERED_HEIGHT), (1,SURFACE2D_LAYERED_LAYERS) } Cubemap { (1,TEXTURECUBEMAP_WIDTH), (1,TEXTURECUBEMAP_WIDTH), 6 } { (1,SURFACECUBEMAP_WIDTH), (1,SURFACECUBEMAP_WIDTH), 6 } Cubemap Layered { (1,TEXTURECUBEMAP_LAYERED_WIDTH), (1,TEXTURECUBEMAP_LAYERED_WIDTH), (1,TEXTURECUBEMAP_LAYERED_LAYERS) } { (1,SURFACECUBEMAP_LAYERED_WIDTH), (1,SURFACECUBEMAP_LAYERED_WIDTH), (1,SURFACECUBEMAP_LAYERED_LAYERS) }

Parameters

  • pHandle (MUmipmappedArray *): Returned mipmapped array
  • pMipmappedArrayDesc (const MUSA_ARRAY3D_DESCRIPTOR *): mipmapped array descriptor
  • numMipmapLevels (unsigned int): Number of mipmap levels

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMipmappedArrayGetLevel​

MUresult muMipmappedArrayGetLevel(MUarray *pLevelArray, MUmipmappedArray hMipmappedArray, unsigned int level)

Description

  • Gets a mipmap level of a MUSA mipmapped array.
  • Returns in *pLevelArray a MUSA array that represents a single mipmap level of the MUSA mipmapped array hMipmappedArray.
  • If level is greater than the maximum number of levels in this mipmapped array, MUSA_ERROR_INVALID_VALUE is returned.

Parameters

  • pLevelArray (MUarray *): Returned mipmap level MUSA array
  • hMipmappedArray (MUmipmappedArray): MUSA mipmapped array
  • level (unsigned int): Mipmap level

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMipmappedArrayDestroy​

MUresult muMipmappedArrayDestroy(MUmipmappedArray hMipmappedArray)

Description

  • Destroys a MUSA mipmapped array.
  • Destroys the MUSA mipmapped array hMipmappedArray.

Parameters

  • hMipmappedArray (MUmipmappedArray): Mipmapped array to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ARRAY_IS_MAPPED, MUSA_ERROR_CONTEXT_IS_DESTROYED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemGetHandleForAddressRange​

MUresult muMemGetHandleForAddressRange(void *handle, MUdeviceptr dptr, size_t size, MUmemRangeHandleType handleType, unsigned long long flags)

Description

  • Retrieve handle for an address range.
  • Get a handle of the specified type to an address range. The address range must have been obtained by a prior call to either muMemAlloc or muMemAddressReserve. If the address range was obtained via muMemAddressReserve, it must also be fully mapped via muMemMap. The address range must have been obtained by a prior call to either muMemAllocHost or muMemHostAlloc on Tegra.
  • Users must ensure the dptr and size are aligned to the host page size.
  • When requesting MUmemRangeHandleType::MU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD, users are expected to query for dma_buf support for the platform by using MU_DEVICE_ATTRIBUTE_DMA_BUF_SUPPORTED device attribute before calling this API. The handle will be interpreted as a pointer to an integer to store the dma_buf file descriptor. Users must ensure the entire address range is backed and mapped when the address range is allocated by muMemAddressReserve. All the physical allocations backing the address range must be resident on the same device and have identical allocation properties. Users are also expected to retrieve a new handle every time the underlying physical allocation(s) corresponding to a previously queried VA range are changed.
  • For MUmemRangeHandleType::MU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD, users may set flags to MU_MEM_RANGE_FLAG_DMA_BUF_MAPPING_TYPE_PCIE. Which when set on a supported platform, will give a DMA_BUF handle mapped via PCIE BAR1 or will return an error otherwise.

Parameters

  • handle (void *): Pointer to the location where the returned handle will be stored.
  • dptr (MUdeviceptr): Pointer to a valid MUSA device allocation. Must be aligned to host page size.
  • size (size_t): Length of the address range. Must be aligned to host page size.
  • handleType (MUmemRangeHandleType): Type of handle requested (defines type and size of the handle output parameter)
  • flags (unsigned long long): When requesting MUmemRangeHandleType::MU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD the value could be MU_MEM_RANGE_FLAG_DMA_BUF_MAPPING_TYPE_PCIE, otherwise 0.

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE MUSA_ERROR_NOT_SUPPORTED

muMemoryTransfer​

MUresult muMemoryTransfer(MUdeviceptr dst, MUdeviceptr src, size_t ByteCount)

Description

  • Copies memory from Device to Device by transfer engine.
  • Copies from device memory to device memory. dst and src are the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dst (MUdeviceptr): Destination device pointer
  • src (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muMemoryTransfer_ptds.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemoryTransferAsync​

MUresult muMemoryTransferAsync(MUdeviceptr dst, MUdeviceptr src, size_t ByteCount, MUstream hStream)

Description

  • Copies memory from Device to Device by transfer engine asynchronously.
  • Copies from device memory to device memory. dst and src are the base pointers of the destination and source, respectively. ByteCount specifies the number of bytes to copy.

Parameters

  • dst (MUdeviceptr): Destination device pointer
  • src (MUdeviceptr): Source device pointer
  • ByteCount (size_t): Size of memory copy in bytes
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muMemoryTransferAsync_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

3.13 Virtual Memory Management​

muMemAddressReserve​

MUresult muMemAddressReserve(MUdeviceptr *ptr, size_t size, size_t alignment, MUdeviceptr addr, unsigned long long flags)

Description

  • Allocate an address range reservation.
  • Reserves a virtual address range based on the given parameters, giving the starting address of the range in ptr. This API requires a system that supports UVA. The size and address parameters must be a multiple of the host page size and the alignment must be a power of two or zero for default alignment.

Parameters

  • ptr (MUdeviceptr *): Resulting pointer to start of virtual address range allocated
  • size (size_t): Size of the reserved virtual address range requested
  • alignment (size_t): Alignment of the reserved virtual address range requested
  • addr (MUdeviceptr): Fixed starting address range requested
  • flags (unsigned long long): Currently unused, must be zero

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemAddressFree​

MUresult muMemAddressFree(MUdeviceptr ptr, size_t size)

Description

  • Free an address range reservation.
  • Frees a virtual address range reserved by muMemAddressReserve. The size must match what was given to memAddressReserve and the ptr given must match what was returned from memAddressReserve.

Parameters

  • ptr (MUdeviceptr): Starting address of the virtual address range to free
  • size (size_t): Size of the virtual address region to free

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemCreate​

MUresult muMemCreate(MUmemGenericAllocationHandle *handle, size_t size, const MUmemAllocationProp *prop, unsigned long long flags)

Description

  • Create a MUSA memory handle representing a memory allocation of a given size described by the given properties.
  • This creates a memory allocation on the target device specified through the prop structure. The created allocation will not have any device or host mappings. The generic memory handle for the allocation can be mapped to the address space of calling process via muMemMap. This handle cannot be transmitted directly to other processes (see muMemExportToShareableHandle). On Windows, the caller must also pass an LPSECURITYATTRIBUTE in prop to be associated with this handle which limits or allows access to this handle for a recipient process (see MUmemAllocationProp::win32HandleMetaData for more). The size of this allocation must be a multiple of the the value given via muMemGetAllocationGranularity with the MU_MEM_ALLOC_GRANULARITY_MINIMUM flag. To create a CPU allocation that doesn't target any specific NUMA nodes, applications must set MUmemAllocationProp::MUmemLocation::type to MU_MEM_LOCATION_TYPE_HOST. MUmemAllocationProp::MUmemLocation::id is ignored for HOST allocations. HOST allocations are not IPC capable and MUmemAllocationProp::requestedHandleTypes must be 0, any other value will result in MUSA_ERROR_INVALID_VALUE. To create a CPU allocation targeting a specific host NUMA node, applications must set MUmemAllocationProp::MUmemLocation::type to MU_MEM_LOCATION_TYPE_HOST_NUMA and MUmemAllocationProp::MUmemLocation::id must specify the NUMA ID of the CPU. On systems where NUMA is not available MUmemAllocationProp::MUmemLocation::id must be set to 0. Specifying MU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT or MU_MEM_LOCATION_TYPE_HOST as the MUmemLocation::type will result in MUSA_ERROR_INVALID_VALUE.
  • Applications that intend to use MU_MEM_HANDLE_TYPE_FABRIC based memory sharing must ensure: (1) mthreads-caps-imex-channels character device is created by the driver and is listed under /proc/devices (2) have at least one IMEX channel file accessible by the user launching the application.
  • When exporter and importer MUSA processes have been granted access to the same IMEX channel, they can securely share memory.
  • The IMEX channel security model works on a per user basis. Which means all processes under a user can share memory if the user has access to a valid IMEX channel. When multi-user isolation is desired, a separate IMEX channel is required for each user.
  • These channel files exist in /dev/mthreads-caps-imex-channels/channel* and can be created using standard OS native calls like mknod on Linux. For example: To create channel0 with the major number from /proc/devices users can execute the following command: mknod /dev/mthreads-caps-imex-channels/channel0 c <major number> 0
  • If MUmemAllocationProp::allocFlags::usage contains MU_MEM_CREATE_USAGE_TILE_POOL flag then the memory allocation is intended only to be used as backing tile pool for sparse MUSA arrays and sparse MUSA mipmapped arrays. (see muMemMapArrayAsync).

Parameters

  • handle (MUmemGenericAllocationHandle *): Value of handle returned. All operations on this allocation are to be performed using this handle.
  • size (size_t): Size of the allocation requested
  • prop (const MUmemAllocationProp *): Properties of the allocation to create.
  • flags (unsigned long long): flags for future use, must be zero now.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemRelease​

MUresult muMemRelease(MUmemGenericAllocationHandle handle)

Description

  • Release a memory handle representing a memory allocation which was previously allocated through muMemCreate.
  • Frees the memory that was allocated on a device through muMemCreate.
  • The memory allocation will be freed when all outstanding mappings to the memory are unmapped and when all outstanding references to the handle (including it's shareable counterparts) are also released. The generic memory handle can be freed when there are still outstanding mappings made with this handle. Each time a recipient process imports a shareable handle, it needs to pair it with muMemRelease for the handle to be freed. If handle is not a valid handle the behavior is undefined.

Parameters

  • handle (MUmemGenericAllocationHandle): Value of handle which was returned previously by muMemCreate.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemMap​

MUresult muMemMap(MUdeviceptr ptr, size_t size, size_t offset, MUmemGenericAllocationHandle handle, unsigned long long flags)

Description

  • Maps an allocation handle to a reserved virtual address range.
  • Maps bytes of memory represented by handle starting from byte offset to size to address range [addr, addr + size]. This range must be an address reservation previously reserved with muMemAddressReserve, and offset + size must be less than the size of the memory allocation. Both ptr, size, and offset must be a multiple of the value given via muMemGetAllocationGranularity with the MU_MEM_ALLOC_GRANULARITY_MINIMUM flag. If handle represents a multicast object, ptr, size and offset must be aligned to the value returned by muMulticastGetGranularity with the flag MU_MULTICAST_MINIMUM_GRANULARITY. For best performance however, it is recommended that ptr, size and offset be aligned to the value returned by muMulticastGetGranularity with the flag MU_MULTICAST_RECOMMENDED_GRANULARITY.
  • When handle represents a multicast object, this call may return MUSA_ERROR_ILLEGAL_STATE if the system configuration is in an illegal state. In such cases, to continue using multicast, verify that the system configuration is in a valid state and all required driver daemons are running properly.
  • Please note calling muMemMap does not make the address accessible, the caller needs to update accessibility of a contiguous mapped VA range by calling muMemSetAccess.
  • Once a recipient process obtains a shareable memory handle from muMemImportFromShareableHandle, the process must use muMemMap to map the memory into its address ranges before setting accessibility with muMemSetAccess.
  • muMemMap can only create mappings on VA range reservations that are not currently mapped.

Parameters

  • ptr (MUdeviceptr): Address where memory will be mapped.
  • size (size_t): Size of the memory mapping.
  • offset (size_t): Offset into the memory represented by handle from which to start mapping Note: currently must be zero. handle from which to start mapping Note: currently must be zero.
  • handle (MUmemGenericAllocationHandle): Handle to a shareable memory
  • flags (unsigned long long): flags for future use, must be zero now.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_ILLEGAL_STATE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemUnmap​

MUresult muMemUnmap(MUdeviceptr ptr, size_t size)

Description

  • Maps or unmaps subregions of sparse MUSA arrays and sparse MUSA mipmapped arrays.
  • Performs map or unmap operations on subregions of sparse MUSA arrays and sparse MUSA mipmapped arrays. Each operation is specified by a MUarrayMapInfo entry in the mapInfoList array of size count. The structure MUarrayMapInfo is defined as follow:
typedef struct MUarray MapInfo_st {
  MUresourcetype resourceType;
  union {
    MUmipmappedArray mipmap;
    MUarray array;
  } resource;
  MUarray SparseSubresourceTypesubresourceType;
  union {
    struct {
      unsigned int level;
      unsigned int layer;
      unsigned int offsetX;
      unsigned int offsetY;
      unsigned int offsetZ;
      unsigned int extentWidth;
      unsigned int extentHeight;
      unsigned int extentDepth;
    } sparseLevel;
    struct {
      unsigned int layer;
      unsigned long long offset;
      unsigned long long size;
    } miptail;
  } subresource;
  MUmemOperationTypememOperationType;
  MUmemHandleTypememHandleType;
  union {
    MUmemGenericAllocationHandlememHandle;
  } memHandle;
  unsigned long long offset;
  unsigned int deviceBitMask;
  unsigned int flags;
  unsigned int reserved[2];
} MUarray MapInfo;
  • where MUarrayMapInfo::resourceType specifies the type of resource to be operated on. If MUarrayMapInfo::resourceType is set to MUresourcetype::MU_RESOURCE_TYPE_ARRAY then MUarrayMapInfo::resource::array must be set to a valid sparse MUSA array handle. The MUSA array must be either a 2D, 2D layered or 3D MUSA array and must have been allocated using muArrayCreate or muArray3DCreate with the flag MUSA_ARRAY3D_SPARSE or MUSA_ARRAY3D_DEFERRED_MAPPING. For MUSA arrays obtained using muMipmappedArrayGetLevel, MUSA_ERROR_INVALID_VALUE will be returned. If MUarrayMapInfo::resourceType is set to MUresourcetype::MU_RESOURCE_TYPE_MIPMAPPED_ARRAY then MUarrayMapInfo::resource::mipmap must be set to a valid sparse MUSA mipmapped array handle. The MUSA mipmapped array must be either a 2D, 2D layered or 3D MUSA mipmapped array and must have been allocated using muMipmappedArrayCreate with the flag MUSA_ARRAY3D_SPARSE or MUSA_ARRAY3D_DEFERRED_MAPPING.
  • MUarrayMapInfo::subresourceType specifies the type of subresource within the resource. MUarraySparseSubresourceType_enum is defined as:
typedef enum MUarray SparseSubresourceType_enum {
  MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_SPARSE_LEVEL = 0,
  MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_MIPTAIL = 1;
} MUarray SparseSubresourceType;
  • where MUarraySparseSubresourceType::MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_SPARSE_LEVEL indicates a sparse-miplevel which spans at least one tile in every dimension. The remaining miplevels which are too small to span at least one tile in any dimension constitute the mip tail region as indicated by MUarraySparseSubresourceType::MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_MIPTAIL subresource type.
  • If MUarrayMapInfo::subresourceType is set to MUarraySparseSubresourceType::MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_SPARSE_LEVEL then MUarrayMapInfo::subresource::sparseLevel struct must contain valid array subregion offsets and extents. The MUarrayMapInfo::subresource::sparseLevel::offsetX, MUarrayMapInfo::subresource::sparseLevel::offsetY and MUarrayMapInfo::subresource::sparseLevel::offsetZ must specify valid X, Y and Z offsets respectively. The MUarrayMapInfo::subresource::sparseLevel::extentWidth, MUarrayMapInfo::subresource::sparseLevel::extentHeight and MUarrayMapInfo::subresource::sparseLevel::extentDepth must specify valid width, height and depth extents respectively. These offsets and extents must be aligned to the corresponding tile dimension. For MUSA mipmapped arrays MUarrayMapInfo::subresource::sparseLevel::level must specify a valid mip level index. Otherwise, must be zero. For layered MUSA arrays and layered MUSA mipmapped arrays MUarrayMapInfo::subresource::sparseLevel::layer must specify a valid layer index. Otherwise, must be zero. MUarrayMapInfo::subresource::sparseLevel::offsetZ must be zero and MUarrayMapInfo::subresource::sparseLevel::extentDepth must be set to 1 for 2D and 2D layered MUSA arrays and MUSA mipmapped arrays. Tile extents can be obtained by calling muArrayGetSparseProperties and muMipmappedArrayGetSparseProperties
  • If MUarrayMapInfo::subresourceType is set to MUarraySparseSubresourceType::MU_ARRAY_SPARSE_SUBRESOURCE_TYPE_MIPTAIL then MUarrayMapInfo::subresource::miptail struct must contain valid mip tail offset in MUarrayMapInfo::subresource::miptail::offset and size in MUarrayMapInfo::subresource::miptail::size. Both, mip tail offset and mip tail size must be aligned to the tile size. For layered MUSA mipmapped arrays which don't have the flag MU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL set in MUSA_ARRAY_SPARSE_PROPERTIES::flags as returned by muMipmappedArrayGetSparseProperties, MUarrayMapInfo::subresource::miptail::layer must specify a valid layer index. Otherwise, must be zero.
  • If MUarrayMapInfo::resource::array or MUarrayMapInfo::resource::mipmap was created with MUSA_ARRAY3D_DEFERRED_MAPPING flag set the MUarrayMapInfo::subresourceType and the contents of MUarrayMapInfo::subresource will be ignored.
  • MUarrayMapInfo::memOperationType specifies the type of operation. MUmemOperationType is defined as:
typedef enum MUmemOperationType_enum {
  MU_MEM_OPERATION_TYPE_MAP = 1,
  MU_MEM_OPERATION_TYPE_UNMAP = 2;
} MUmemOperationType;
  • If MUarrayMapInfo::memOperationType is set to MUmemOperationType::MU_MEM_OPERATION_TYPE_MAP then the subresource will be mapped onto the tile pool memory specified by MUarrayMapInfo::memHandle at offset MUarrayMapInfo::offset. The tile pool allocation has to be created by specifying the MU_MEM_CREATE_USAGE_TILE_POOL flag when calling muMemCreate. Also, MUarrayMapInfo::memHandleType must be set to MUmemHandleType::MU_MEM_HANDLE_TYPE_GENERIC.
  • If MUarrayMapInfo::memOperationType is set to MUmemOperationType::MU_MEM_OPERATION_TYPE_UNMAP then an unmapping operation is performed. MUarrayMapInfo::memHandle must be NULL.
  • MUarrayMapInfo::deviceBitMask specifies the list of devices that must map or unmap physical memory. Currently, this mask must have exactly one bit set, and the corresponding device must match the device associated with the stream. If MUarrayMapInfo::memOperationType is set to MUmemOperationType::MU_MEM_OPERATION_TYPE_MAP, the device must also match the device associated with the tile pool memory allocation as specified by MUarrayMapInfo::memHandle.
  • MUarrayMapInfo::flags and MUarrayMapInfo::reserved[] are unused and must be set to zero.
  • The range must be the entire contiguous address range that was mapped to. In other words, muMemUnmap cannot unmap a sub-range of an address range mapped by muMemCreate / muMemMap. Any backing memory allocations will be freed if there are no existing mappings and there are no unreleased memory handles.
  • When muMemUnmap returns successfully the address range is converted to an address reservation and can be used for a future calls to muMemMap. Any new mapping to this virtual address will need to have access granted through muMemSetAccess, as all mappings start with no accessibility setup.

Parameters

  • ptr (MUdeviceptr): Starting address for the virtual address range to unmap
  • size (size_t): Size of the virtual address range to unmap

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE
  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemSetAccess​

MUresult muMemSetAccess(MUdeviceptr ptr, size_t size, const MUmemAccessDesc *desc, size_t count)

Description

  • Set the access flags for each location specified in desc for the given virtual address range.
  • Given the virtual address range via ptr and size, and the locations in the array given by desc and count, set the access flags for the target locations. The range must be a fully mapped address range containing all allocations created by muMemMap / muMemCreate. Users cannot specify MU_MEM_LOCATION_TYPE_HOST_NUMA accessibility for allocations created on with other location types. Note: When MUmemAccessDesc::MUmemLocation::type is MU_MEM_LOCATION_TYPE_HOST_NUMA, MUmemAccessDesc::MUmemLocation::id is ignored. When setting the access flags for a virtual address range mapping a multicast object, ptr and size must be aligned to the value returned by muMulticastGetGranularity with the flag MU_MULTICAST_MINIMUM_GRANULARITY. For best performance however, it is recommended that ptr and size be aligned to the value returned by muMulticastGetGranularity with the flag MU_MULTICAST_RECOMMENDED_GRANULARITY.

Parameters

  • ptr (MUdeviceptr): Starting address for the virtual address range
  • size (size_t): Length of the virtual address range
  • desc (const MUmemAccessDesc *): Array of MUmemAccessDesc that describe how to change the mapping for each location specified mapping for each location specified
  • count (size_t): Number of MUmemAccessDesc in desc

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for synchronization behavior.

See also

muMemGetAccess​

MUresult muMemGetAccess(unsigned long long *flags, const MUmemLocation *location, MUdeviceptr ptr)

Description

  • Get the access flags set for the given location and ptr.

Parameters

  • flags (unsigned long long *): Flags set for this location
  • location (const MUmemLocation *): Location in which to check the flags for
  • ptr (MUdeviceptr): Address in which to check the access flags for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemExportToShareableHandle​

MUresult muMemExportToShareableHandle(void *shareableHandle, MUmemGenericAllocationHandle handle, MUmemAllocationHandleType handleType, unsigned long long flags)

Description

  • Exports an allocation to a requested shareable handle type.
  • Given a MUSA memory handle, create a shareable memory allocation handle that can be used to share the memory with other processes. The recipient process can convert the shareable handle back into a MUSA memory handle using muMemImportFromShareableHandle and map it with muMemMap. The implementation of what this handle is and how it can be transferred is defined by the requested handle type in handleType
  • Once all shareable handles are closed and the allocation is released, the allocated memory referenced will be released back to the OS and uses of the MUSA handle afterward will lead to undefined behavior.
  • This API can also be used in conjunction with other APIs (e.g. Vulkan, OpenGL) that support importing memory from the shareable type

Parameters

  • shareableHandle (void *): Pointer to the location in which to store the requested handle type
  • handle (MUmemGenericAllocationHandle): MUSA handle for the memory allocation
  • handleType (MUmemAllocationHandleType): Type of shareable handle requested (defines type and size of the shareableHandle output parameter)
  • flags (unsigned long long): Reserved, must be zero

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemImportFromShareableHandle​

MUresult muMemImportFromShareableHandle(MUmemGenericAllocationHandle *handle, void *osHandle, MUmemAllocationHandleType shHandleType)

Description

  • Imports an allocation from a requested shareable handle type.
  • If the current process cannot support the memory described by this shareable handle, this API will error as MUSA_ERROR_NOT_SUPPORTED.
  • If shHandleType is MU_MEM_HANDLE_TYPE_FABRIC and the importer process has not been granted access to the same IMEX channel as the exporter process, this API will error as MUSA_ERROR_NOT_PERMITTED.

Parameters

  • handle (MUmemGenericAllocationHandle *): MUSA Memory handle for the memory allocation.
  • osHandle (void *): Shareable Handle representing the memory allocation that is to be imported.
  • shHandleType (MUmemAllocationHandleType): handle type of the exported handle MUmemAllocationHandleType.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • Importing shareable handles exported from some graphics APIs(VUlkan, OpenGL, etc) created on devices under an SLI group may not be supported, and thus this API will return MUSA_ERROR_NOT_SUPPORTED. There is no guarantee that the contents of handle will be the same MUSA memory handle for the same given OS shareable handle, or the same underlying allocation.

See also

muMemGetAllocationGranularity​

MUresult muMemGetAllocationGranularity(size_t *granularity, const MUmemAllocationProp *prop, MUmemAllocationGranularity_flags option)

Description

  • Calculates either the minimal or recommended granularity.
  • Calculates either the minimal or recommended granularity for a given allocation specification and returns it in granularity. This granularity can be used as a multiple for alignment, size, or address mapping.

Parameters

  • granularity (size_t *): Returned granularity.
  • prop (const MUmemAllocationProp *): Property for which to determine the granularity for
  • option (MUmemAllocationGranularity_flags): Determines which granularity to return

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemGetAllocationPropertiesFromHandle​

MUresult muMemGetAllocationPropertiesFromHandle(MUmemAllocationProp *prop, MUmemGenericAllocationHandle handle)

Description

  • Retrieve the contents of the property structure defining properties for this handle.

Parameters

  • prop (MUmemAllocationProp *): Pointer to a properties structure which will hold the information about this handle
  • handle (MUmemGenericAllocationHandle): Handle which to perform the query on

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

See also

muMemRetainAllocationHandle​

MUresult muMemRetainAllocationHandle(MUmemGenericAllocationHandle *handle, void *addr)

Description

  • Given an address addr, returns the allocation handle of the backing memory allocation.
  • The handle is guaranteed to be the same handle value used to map the memory. If the address requested is not mapped, the function will fail. The returned handle must be released with corresponding number of calls to muMemRelease.

Parameters

  • handle (MUmemGenericAllocationHandle *): MUSA Memory handle for the backing memory allocation.
  • addr (void *): Memory address to query, that has been mapped previously.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_NOT_SUPPORTED

Note

  • The address addr, can be any address in a range previously mapped by muMemMap, and not necessarily the start address.

See also

3.14 Stream Ordered Memory Allocator​

muMemFreeAsync​

MUresult muMemFreeAsync(MUdeviceptr dptr, MUstream hStream)

Description

  • Frees memory with stream ordered semantics.
  • Inserts a free operation into hStream. The allocation must not be accessed after stream execution reaches the free. After this API returns, accessing the memory from any subsequent work launched on the GPU or querying its pointer attributes results in undefined behavior.

Parameters

  • dptr (MUdeviceptr): memory to free
  • hStream (MUstream): The stream establishing the stream ordering contract.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT (default stream specified with no current context), MUSA_ERROR_NOT_SUPPORTED

Note

  • During stream capture, this function results in the creation of a free node and must therefore be passed the address of a graph allocation.

muMemAllocAsync​

MUresult muMemAllocAsync(MUdeviceptr *dptr, size_t bytesize, MUstream hStream)

Description

  • Allocates memory with stream ordered semantics.
  • Inserts an allocation operation into hStream. A pointer to the allocated memory is returned immediately in *dptr. The allocation must not be accessed until the the allocation operation completes. The allocation comes from the memory pool current to the stream's device.

Parameters

  • dptr (MUdeviceptr *): Returned device pointer
  • bytesize (size_t): Number of bytes to allocate
  • hStream (MUstream): The stream establishing the stream ordering contract and the memory pool to allocate from

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT (default stream specified with no current context), MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_OUT_OF_MEMORY

Note

  • The default memory pool of a device contains device memory from that device.
  • Basic stream ordering allows future work submitted into the same stream to use the allocation. Stream query, stream synchronize, and MUSA events can be used to guarantee that the allocation operation completes before work submitted in a separate stream runs.
  • During stream capture, this function results in the creation of an allocation node. In this case, the allocation is owned by the graph instead of the memory pool. The memory pool's properties are used to set the node's creation parameters.

See also

muMemPoolTrimTo​

MUresult muMemPoolTrimTo(MUmemoryPool pool, size_t minBytesToKeep)

Description

  • Tries to release memory back to the OS.
  • Releases memory back to the OS until the pool contains fewer than minBytesToKeep reserved bytes, or there is no more memory that the allocator can safely release. The allocator cannot release OS allocations that back outstanding asynchronous allocations. The OS allocations may happen at different granularity from the user allocations.

Parameters

  • pool (MUmemoryPool): The memory pool to trim
  • minBytesToKeep (size_t): If the pool has less than minBytesToKeep reserved, the TrimTo operation is a no-op. Otherwise the pool will be guaranteed to have at least minBytesToKeep bytes reserved after the operation.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • : Allocations that have not been freed count as outstanding.
  • : Allocations that have been asynchronously freed but whose completion has not been observed on the host (eg. by a synchronize) can count as outstanding.

See also

muMemPoolSetAttribute​

MUresult muMemPoolSetAttribute(MUmemoryPool pool, MUmemPool_attribute attr, void *value)

Description

  • Sets attributes of a memory pool.
  • Supported attributes are: MU_MEMPOOL_ATTR_RELEASE_THRESHOLD: (value type = muuint64_t) Amount of reserved memory in bytes to hold onto before trying to release memory back to the OS. When more than the release threshold bytes of memory are held by the memory pool, the allocator will try to release memory back to the OS on the next call to stream, event or context synchronize. (default 0) MU_MEMPOOL_ATTR_REUSE_FOLLOW_EVENT_DEPENDENCIES: (value type = int) Allow muMemAllocAsync to use memory asynchronously freed in another stream as long as a stream ordering dependency of the allocating stream on the free action exists. Musa events and null stream interactions can create the required stream ordered dependencies. (default enabled) MU_MEMPOOL_ATTR_REUSE_ALLOW_OPPORTUNISTIC: (value type = int) Allow reuse of already completed frees when there is no dependency between the free and allocation. (default enabled) MU_MEMPOOL_ATTR_REUSE_ALLOW_INTERNAL_DEPENDENCIES: (value type = int) Allow muMemAllocAsync to insert new stream dependencies in order to establish the stream ordering required to reuse a piece of memory released by muMemFreeAsync (default enabled). MU_MEMPOOL_ATTR_RESERVED_MEM_HIGH: (value type = muuint64_t) Reset the high watermark that tracks the amount of backing memory that was allocated for the memory pool. It is illegal to set this attribute to a non-zero value. MU_MEMPOOL_ATTR_USED_MEM_HIGH: (value type = muuint64_t) Reset the high watermark that tracks the amount of used memory that was allocated for the memory pool.

Parameters

  • pool (MUmemoryPool): The memory pool to modify
  • attr (MUmemPool_attribute): The attribute to modify
  • value (void *): Pointer to the value to assign

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

See also

muMemPoolGetAttribute​

MUresult muMemPoolGetAttribute(MUmemoryPool pool, MUmemPool_attribute attr, void *value)

Description

  • Gets attributes of a memory pool.
  • Supported attributes are: MU_MEMPOOL_ATTR_RELEASE_THRESHOLD: (value type = muuint64_t) Amount of reserved memory in bytes to hold onto before trying to release memory back to the OS. When more than the release threshold bytes of memory are held by the memory pool, the allocator will try to release memory back to the OS on the next call to stream, event or context synchronize. (default 0) MU_MEMPOOL_ATTR_REUSE_FOLLOW_EVENT_DEPENDENCIES: (value type = int) Allow muMemAllocAsync to use memory asynchronously freed in another stream as long as a stream ordering dependency of the allocating stream on the free action exists. Musa events and null stream interactions can create the required stream ordered dependencies. (default enabled) MU_MEMPOOL_ATTR_REUSE_ALLOW_OPPORTUNISTIC: (value type = int) Allow reuse of already completed frees when there is no dependency between the free and allocation. (default enabled) MU_MEMPOOL_ATTR_REUSE_ALLOW_INTERNAL_DEPENDENCIES: (value type = int) Allow muMemAllocAsync to insert new stream dependencies in order to establish the stream ordering required to reuse a piece of memory released by muMemFreeAsync (default enabled). MU_MEMPOOL_ATTR_RESERVED_MEM_CURRENT: (value type = muuint64_t) Amount of backing memory currently allocated for the mempool MU_MEMPOOL_ATTR_RESERVED_MEM_HIGH: (value type = muuint64_t) High watermark of backing memory allocated for the mempool since the last time it was reset. MU_MEMPOOL_ATTR_USED_MEM_CURRENT: (value type = muuint64_t) Amount of memory from the pool that is currently in use by the application. MU_MEMPOOL_ATTR_USED_MEM_HIGH: (value type = muuint64_t) High watermark of the amount of memory from the pool that was in use by the application.
  • The following properties can be also be queried on imported and default pools: MU_MEMPOOL_ATTR_ALLOCATION_TYPE: (value type = MUmemAllocationType) The allocation type of the mempool MU_MEMPOOL_ATTR_EXPORT_HANDLE_TYPES: (value type = MUmemAllocationHandleType) Available export handle types for the mempool. For imported pools this value is always MU_MEM_HANDLE_TYPE_NONE as an imported pool cannot be re-exported MU_MEMPOOL_ATTR_LOCATION_ID: (value type = int) The location id for the mempool. If the location type for this pool is MU_MEM_LOCATION_TYPE_INVISIBLE then ID will be MU_DEVICE_INVALID. MU_MEMPOOL_ATTR_LOCATION_TYPE: (value type = MUmemLocationType) The location type for the mempool. For imported memory pools where the device is not directly visible to the importing process or pools imported via fabric handles across nodes this will be MU_MEM_LOCATION_TYPE_INVISIBLE. MU_MEMPOOL_ATTR_MAX_POOL_SIZE: (value type = muuint64_t) Maximum size of the pool in bytes, this value may be higher than what was initially passed to muMemPoolCreate due to alignment requirements. A value of 0 indicates no maximum size. For MU__MEM_ALLOCATION_TYPE_MANAGED and IPC imported pools this value will be system dependent. MU_MEMPOOL_ATTR_HW_DECOMPRESS_ENABLED: (value type = int) Indicates whether the pool has hardware compresssion enabled pool - The memory pool to get attributes of attr - The attribute to get value - Retrieved value MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE muMemAllocAsync, muMemFreeAsync, muDeviceGetDefaultMemPool, muDeviceGetMemPool, muMemPoolCreate

Parameters

  • pool (MUmemoryPool): The memory pool to get attributes of
  • attr (MUmemPool_attribute): The attribute to get
  • value (void *): Retrieved value

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

See also

muMemPoolSetAccess​

MUresult muMemPoolSetAccess(MUmemoryPool pool, const MUmemAccessDesc *map, size_t count)

Description

  • Controls visibility of pools between devices.

Parameters

  • pool (MUmemoryPool): The pool being modified
  • map (const MUmemAccessDesc *): Array of access descriptors. Each descriptor instructs the access to enable for a single gpu.
  • count (size_t): Number of descriptors in the map array.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

See also

muMemPoolGetAccess​

MUresult muMemPoolGetAccess(MUmemAccess_flags *flags, MUmemoryPool memPool, MUmemLocation *location)

Description

  • Returns the accessibility of a pool from a device.
  • Returns the accessibility of the pool's memory from the specified location.

Parameters

  • flags (MUmemAccess_flags *): the accessibility of the pool from the specified location
  • memPool (MUmemoryPool): the pool being queried
  • location (MUmemLocation *): the location accessing the pool

Returns

  • Return type: MUresult.

See also

muMemPoolCreate​

MUresult muMemPoolCreate(MUmemoryPool *pool, const MUmemPoolProps *poolProps)

Description

  • Creates a memory pool.
  • Creates a MUSA memory pool and returns the handle in pool. The poolProps determines the properties of the pool such as the backing device and IPC capabilities.
  • To create a memory pool for HOST memory not targeting a specific NUMA node, applications must set set MUmemPoolProps::MUmemLocation::type to MU_MEM_LOCATION_TYPE_HOST. MUmemPoolProps::MUmemLocation::id is ignored for such pools. Pools created with the type MU_MEM_LOCATION_TYPE_HOST are not IPC capable and MUmemPoolProps::handleTypes must be 0, any other values will result in MUSA_ERROR_INVALID_VALUE. To create a memory pool targeting a specific host NUMA node, applications must set MUmemPoolProps::MUmemLocation::type to MU_MEM_LOCATION_TYPE_HOST_NUMA and MUmemPoolProps::MUmemLocation::id must specify the NUMA ID of the host memory node. Specifying MU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT or MU_MEM_LOCATION_TYPE_HOST as the MUmemPoolProps::MUmemLocation::type will result in MUSA_ERROR_INVALID_VALUE. By default, the pool's memory will be accessible from the device it is allocated on. In the case of pools created with MU_MEM_LOCATION_TYPE_HOST_NUMA, their default accessibility will be from the host CPU. Applications can control the maximum size of the pool by specifying a non-zero value for MUmemPoolProps::maxSize. If set to 0, the maximum size of the pool will default to a system dependent value.
  • Applications that intend to use MU_MEM_HANDLE_TYPE_FABRIC based memory sharing must ensure: (1) mthreads-caps-imex-channels character device is created by the driver and is listed under /proc/devices (2) have at least one IMEX channel file accessible by the user launching the application.
  • When exporter and importer MUSA processes have been granted access to the same IMEX channel, they can securely share memory.
  • The IMEX channel security model works on a per user basis. Which means all processes under a user can share memory if the user has access to a valid IMEX channel. When multi-user isolation is desired, a separate IMEX channel is required for each user.
  • These channel files exist in /dev/mthreads-caps-imex-channels/channel* and can be created using standard OS native calls like mknod on Linux. For example: To create channel0 with the major number from /proc/devices users can execute the following command: mknod /dev/mthreads-caps-imex-channels/channel0 c <major number> 0
  • To create a managed memory pool, applications must set MUmemPoolProps::MUmemAllocationType to MU_MEM_ALLOCATION_TYPE_MANAGED. MUmemPoolProps::MUmemAllocationHandleType must also be set to MU_MEM_HANDLE_TYPE_NONE since IPC is not supported. For managed memory pools, MUmemPoolProps::MUmemLocation will be treated as the preferred location for all allocations created from the pool. An application can also set MU_MEM_LOCATION_TYPE_NONE to indicate no preferred location. MUmemPoolProps::maxSize must be set to zero for managed memory pools. MUmemPoolProps::usage should be zero as decompress for managed memory is not supported. For managed memory pools, all devices on the system must have non-zero concurrentManagedAccess. If not, this call returns MUSA_ERROR_NOT_SUPPORTED

Parameters

  • pool (MUmemoryPool *)
  • poolProps (const MUmemPoolProps *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY, MUSA_ERROR_NOT_PERMITTED MUSA_ERROR_NOT_SUPPORTED

Note

  • Specifying MU_MEM_HANDLE_TYPE_NONE creates a memory pool that will not support IPC.

See also

muMemPoolDestroy​

MUresult muMemPoolDestroy(MUmemoryPool pool)

Description

  • Destroys the specified memory pool.
  • If any pointers obtained from this pool haven't been freed or the pool has free operations that haven't completed when muMemPoolDestroy is invoked, the function will return immediately and the resources associated with the pool will be released automatically once there are no more outstanding allocations.
  • Destroying the current mempool of a device sets the default mempool of that device as the current mempool for that device.

Parameters

  • pool (MUmemoryPool)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • A device's default memory pool cannot be destroyed.

See also

muMemGetDefaultMemPool​

MUresult muMemGetDefaultMemPool(MUmemoryPool *pool_out, MUmemLocation *location, MUmemAllocationType type)

Description

  • Returns the default memory pool for a given location and allocation type.
  • The memory location can be of one of MU_MEM_LOCATION_TYPE_DEVICE, MU_MEM_LOCATION_TYPE_HOST or MU_MEM_LOCATION_TYPE_HOST_NUMA. The allocation type can be one of MU_MEM_ALLOCATION_TYPE_PINNED or MU_MEM_ALLOCATION_TYPE_MANAGED. When the allocation type is MU_MEM_ALLOCATION_TYPE_MANAGED, the location type can also be MU_MEM_LOCATION_TYPE_NONE to indicate no preferred location for the managed memory pool. In all other cases, the call returns MUSA_ERROR_INVALID_VALUE.

Parameters

  • pool_out (MUmemoryPool *)
  • location (MUmemLocation *)
  • type (MUmemAllocationType)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • This function may also return error codes from previous, asynchronous launches.

See also

muMemGetMemPool​

MUresult muMemGetMemPool(MUmemoryPool *pool, MUmemLocation *location, MUmemAllocationType type)

Description

  • Gets the current memory pool for a memory location and of a particular allocation type.
  • The memory location can be of one of MU_MEM_LOCATION_TYPE_DEVICE, MU_MEM_LOCATION_TYPE_HOST or MU_MEM_LOCATION_TYPE_HOST_NUMA. The allocation type can be one of MU_MEM_ALLOCATION_TYPE_PINNED or MU_MEM_ALLOCATION_TYPE_MANAGED. When the allocation type is MU_MEM_ALLOCATION_TYPE_MANAGED, the location type can also be MU_MEM_LOCATION_TYPE_NONE to indicate no preferred location for the managed memory pool. In all other cases, the call returns MUSA_ERROR_INVALID_VALUE.
  • Returns the last pool provided to muMemSetMemPool or muDeviceSetMemPool for this location and allocation type or the location's default memory pool if muMemSetMemPool or muDeviceSetMemPool for that allocType and location has never been called. By default the current mempool of a location is the default mempool for a device. Otherwise the returned pool must have been set with muDeviceSetMemPool.

Parameters

  • pool (MUmemoryPool *)
  • location (MUmemLocation *)
  • type (MUmemAllocationType)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muMemSetMemPool​

MUresult muMemSetMemPool(MUmemLocation *location, MUmemAllocationType type, MUmemoryPool pool)

Description

  • Sets the current memory pool for a memory location and allocation type.
  • The memory location can be of one of MU_MEM_LOCATION_TYPE_DEVICE, MU_MEM_LOCATION_TYPE_HOST or MU_MEM_LOCATION_TYPE_HOST_NUMA. The allocation type can be one of MU_MEM_ALLOCATION_TYPE_PINNED or MU_MEM_ALLOCATION_TYPE_MANAGED. When the allocation type is MU_MEM_ALLOCATION_TYPE_MANAGED, the location type can also be MU_MEM_LOCATION_TYPE_NONE to indicate no preferred location for the managed memory pool. In all other cases, the call returns MUSA_ERROR_INVALID_VALUE.
  • When a memory pool is set as the current memory pool, the location parameter should be the same as the location of the pool. The location and allocation type specified must match those of the pool otherwise MUSA_ERROR_INVALID_VALUE is returned. By default, a memory location's current memory pool is its default memory pool that can be obtained via muMemGetDefaultMemPool. If the location type is MU_MEM_LOCATION_TYPE_DEVICE and the allocation type is MU_MEM_ALLOCATION_TYPE_PINNED, then this API is the equivalent of calling muDeviceSetMemPool with the location id as the device. For further details on the implications, please refer to the documentation for muDeviceSetMemPool.

Parameters

  • location (MUmemLocation *)
  • type (MUmemAllocationType)
  • pool (MUmemoryPool)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • Use muMemAllocFromPoolAsync to specify asynchronous allocations from a device different than the one the stream runs on.

See also

muMemAllocFromPoolAsync​

MUresult muMemAllocFromPoolAsync(MUdeviceptr *dptr, size_t bytesize, MUmemoryPool pool, MUstream hStream)

Description

  • Allocates memory from a specified pool with stream ordered semantics.
  • Inserts an allocation operation into hStream. A pointer to the allocated memory is returned immediately in *dptr. The allocation must not be accessed until the the allocation operation completes. The allocation comes from the specified memory pool.

Parameters

  • dptr (MUdeviceptr *): Returned device pointer
  • bytesize (size_t): Number of bytes to allocate
  • pool (MUmemoryPool): The pool to allocate from
  • hStream (MUstream): The stream establishing the stream ordering semantic

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT (default stream specified with no current context), MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_OUT_OF_MEMORY

Note

  • The specified memory pool may be from a device different than that of the specified hStream. Basic stream ordering allows future work submitted into the same stream to use the allocation. Stream query, stream synchronize, and MUSA events can be used to guarantee that the allocation operation completes before work submitted in a separate stream runs. The specified memory pool may be from a device different than that of the specified hStream. Basic stream ordering allows future work submitted into the same stream to use the allocation. Stream query, stream synchronize, and MUSA events can be used to guarantee that the allocation operation completes before work submitted in a separate stream runs.
  • During stream capture, this function results in the creation of an allocation node. In this case, the allocation is owned by the graph instead of the memory pool. The memory pool's properties are used to set the node's creation parameters.

See also

muMemPoolExportToShareableHandle​

MUresult muMemPoolExportToShareableHandle(void *handle_out, MUmemoryPool pool, MUmemAllocationHandleType handleType, unsigned long long flags)

Description

  • Exports a memory pool to the requested handle type.
  • Given an IPC capable mempool, create an OS handle to share the pool with another process. A recipient process can convert the shareable handle into a mempool with muMemPoolImportFromShareableHandle. Individual pointers can then be shared with the muMemPoolExportPointer and muMemPoolImportPointer APIs. The implementation of what the shareable handle is and how it can be transferred is defined by the requested handle type.

Parameters

  • handle_out (void *): Returned OS handle
  • pool (MUmemoryPool): pool to export
  • handleType (MUmemAllocationHandleType): the type of handle to create
  • flags (unsigned long long): must be 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_OUT_OF_MEMORY

Note

  • : To create an IPC capable mempool, create a mempool with a MUmemAllocationHandleType other than MU_MEM_HANDLE_TYPE_NONE.

See also

muMemPoolImportFromShareableHandle​

MUresult muMemPoolImportFromShareableHandle(MUmemoryPool *pool_out, void *handle, MUmemAllocationHandleType handleType, unsigned long long flags)

Description

  • imports a memory pool from a shared handle.
  • Specific allocations can be imported from the imported pool with muMemPoolImportPointer.
  • If handleType is MU_MEM_HANDLE_TYPE_FABRIC and the importer process has not been granted access to the same IMEX channel as the exporter process, this API will error as MUSA_ERROR_NOT_PERMITTED.

Parameters

  • pool_out (MUmemoryPool *): Returned memory pool
  • handle (void *): OS handle of the pool to open
  • handleType (MUmemAllocationHandleType): The type of handle being imported
  • flags (unsigned long long): must be 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Imported memory pools do not support creating new allocations. As such imported memory pools may not be used in muDeviceSetMemPool or muMemAllocFromPoolAsync calls.

See also

muMemPoolExportPointer​

MUresult muMemPoolExportPointer(MUmemPoolPtrExportData *shareData_out, MUdeviceptr ptr)

Description

  • Export data to share a memory pool allocation between processes.
  • Constructs shareData_out for sharing a specific allocation from an already shared memory pool. The recipient process can import the allocation with the muMemPoolImportPointer api. The data is not a handle and may be shared through any IPC mechanism.

Parameters

  • shareData_out (MUmemPoolPtrExportData *): Returned export data
  • ptr (MUdeviceptr): pointer to memory being exported

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_OUT_OF_MEMORY

See also

muMemPoolImportPointer​

MUresult muMemPoolImportPointer(MUdeviceptr *ptr_out, MUmemoryPool pool, MUmemPoolPtrExportData *shareData)

Description

  • Import a memory pool allocation from another process.
  • Returns in ptr_out a pointer to the imported memory. The imported memory must not be accessed before the allocation operation completes in the exporting process. The imported memory must be freed from all importing processes before being freed in the exporting process. The pointer may be freed with muMemFree or muMemFreeAsync. If muMemFreeAsync is used, the free must be completed on the importing process before the free operation on the exporting process.

Parameters

  • ptr_out (MUdeviceptr *): pointer to imported memory
  • pool (MUmemoryPool): pool from which to import
  • shareData (MUmemPoolPtrExportData *): data specifying the memory to import

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_OUT_OF_MEMORY

Note

  • The muMemFreeAsync api may be used in the exporting process before the muMemFreeAsync operation completes in its stream as long as the muMemFreeAsync in the exporting process specifies a stream with a stream dependency on the importing process's muMemFreeAsync.

See also

3.15 Unified Addressing​

muPointerGetAttribute​

MUresult muPointerGetAttribute(void *data, MUpointer_attribute attribute, MUdeviceptr ptr)

Description

  • Returns information about a pointer.
  • The supported attributes are:
  • MU_POINTER_ATTRIBUTE_CONTEXT: Returns in *data the MUcontext in which ptr was allocated or registered. The type of data must be MUcontext *. If ptr was not allocated by, mapped by, or registered with a MUcontext which uses unified virtual addressing then MUSA_ERROR_INVALID_VALUE is returned. MU_POINTER_ATTRIBUTE_MEMORY_TYPE: Returns in *data the physical memory type of the memory that ptr addresses as a MUmemorytype enumerated value. The type of data must be unsigned int. If ptr addresses device memory then *data is set to MU_MEMORYTYPE_DEVICE. The particular MUdevice on which the memory resides is the MUdevice of the MUcontext returned by the MU_POINTER_ATTRIBUTE_CONTEXT attribute of ptr. If ptr addresses host memory then *data is set to MU_MEMORYTYPE_HOST. If ptr was not allocated by, mapped by, or registered with a MUcontext which uses unified virtual addressing then MUSA_ERROR_INVALID_VALUE is returned. If the current MUcontext does not support unified virtual addressing then MUSA_ERROR_INVALID_CONTEXT is returned. MU_POINTER_ATTRIBUTE_DEVICE_POINTER: Returns in *data the device pointer value through which ptr may be accessed by kernels running in the current MUcontext. The type of data must be MUdeviceptr *. If there exists no device pointer value through which kernels running in the current MUcontext may access ptr then MUSA_ERROR_INVALID_VALUE is returned. If there is no current MUcontext then MUSA_ERROR_INVALID_CONTEXT is returned. Except in the exceptional disjoint addressing cases discussed below, the value returned in *data will equal the input value ptr. MU_POINTER_ATTRIBUTE_HOST_POINTER: Returns in *data the host pointer value through which ptr may be accessed by by the host program. The type of data must be void **. If there exists no host pointer value through which the host program may directly access ptr then MUSA_ERROR_INVALID_VALUE is returned. Except in the exceptional disjoint addressing cases discussed below, the value returned in *data will equal the input value ptr. MU_POINTER_ATTRIBUTE_P2P_TOKENS: Returns in *data two tokens for use with the nv-p2p.h Linux kernel interface. data must be a struct of type MUSA_POINTER_ATTRIBUTE_P2P_TOKENS. ptr must be a pointer to memory obtained from :muMemAlloc(). Note that p2pToken and vaSpaceToken are only valid for the lifetime of the source allocation. A subsequent allocation at the same address may return completely different tokens. Querying this attribute has a side effect of setting the attribute MU_POINTER_ATTRIBUTE_SYNC_MEMOPS for the region of memory that ptr points to. MU_POINTER_ATTRIBUTE_SYNC_MEMOPS: A boolean attribute which when set, ensures that synchronous memory operations initiated on the region of memory that ptr points to will always synchronize. See further documentation in the section titled "API synchronization behavior" to learn more about cases when synchronous memory operations can exhibit asynchronous behavior. MU_POINTER_ATTRIBUTE_BUFFER_ID: Returns in *data a buffer ID which is guaranteed to be unique within the process. data must point to an unsigned long long. ptr must be a pointer to memory obtained from a MUSA memory allocation API. Every memory allocation from any of the MUSA memory allocation APIs will have a unique ID over a process lifetime. Subsequent allocations do not reuse IDs from previous freed allocations. IDs are only unique within a single process. MU_POINTER_ATTRIBUTE_IS_MANAGED: Returns in *data a boolean that indicates whether the pointer points to managed memory or not. If ptr is not a valid MUSA pointer then MUSA_ERROR_INVALID_VALUE is returned. MU_POINTER_ATTRIBUTE_DEVICE_ORDINAL: Returns in *data an integer representing a device ordinal of a device against which the memory was allocated or registered. MU_POINTER_ATTRIBUTE_IS_LEGACY_MUSA_IPC_CAPABLE: Returns in *data a boolean that indicates if this pointer maps to an allocation that is suitable for musaIpcGetMemHandle. MU_POINTER_ATTRIBUTE_RANGE_START_ADDR: Returns in *data the starting address for the allocation referenced by the device pointer ptr. Note that this is not necessarily the address of the mapped region, but the address of the mappable address range ptr references (e.g. from muMemAddressReserve). MU_POINTER_ATTRIBUTE_RANGE_SIZE: Returns in *data the size for the allocation referenced by the device pointer ptr. Note that this is not necessarily the size of the mapped region, but the size of the mappable address range ptr references (e.g. from muMemAddressReserve). To retrieve the size of the mapped region, see muMemGetAddressRange MU_POINTER_ATTRIBUTE_MAPPED: Returns in *data a boolean that indicates if this pointer is in a valid address range that is mapped to a backing allocation. MU_POINTER_ATTRIBUTE_ALLOWED_HANDLE_TYPES: Returns a bitmask of the allowed handle types for an allocation that may be passed to muMemExportToShareableHandle. MU_POINTER_ATTRIBUTE_MEMPOOL_HANDLE: Returns in *data the handle to the mempool that the allocation was obtained from. MU_POINTER_ATTRIBUTE_IS_HW_DECOMPRESS_CAPABLE: Returns in *data a boolean that indicates whether the pointer points to memory that is capable to be used for hardware accelerated decompression.

Parameters

  • data (void *): Returned pointer attribute value
  • attribute (MUpointer_attribute): Pointer attribute to query
  • ptr (MUdeviceptr): Pointer

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muMemPrefetchAsync​

MUresult muMemPrefetchAsync(MUdeviceptr devPtr, size_t count, MUdevice dstDevice, MUstream hStream)

Description

  • Prefetches memory to the specified destination device.
  • Note there is a later version of this API, muMemPrefetchAsync_v2. It will supplant this version in 13.0, which is retained for minor version compatibility.
  • Prefetches memory to the specified destination device. devPtr is the base device pointer of the memory to be prefetched and dstDevice is the destination device. count specifies the number of bytes to copy. hStream is the stream in which the operation is enqueued. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables or it may also refer to system-allocated memory on systems with non-zero MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS.
  • Passing in MU_DEVICE_CPU for dstDevice will prefetch the data to host memory. If dstDevice is a GPU, then the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS must be non-zero. Additionally, hStream must be associated with a device that has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS.
  • The start address and end address of the memory range will be rounded down and rounded up respectively to be aligned to CPU page size before the prefetch operation is enqueued in the stream.
  • If no physical memory has been allocated for this region, then this memory region will be populated and mapped on the destination device. If there's insufficient memory to prefetch the desired region, the Unified Memory driver may evict pages from other muMemAllocManaged allocations to host memory in order to make room. Device memory allocated using muMemAlloc or muArrayCreate will not be evicted.
  • By default, any mappings to the previous location of the migrated pages are removed and mappings for the new location are only setup on dstDevice. The exact behavior however also depends on the settings applied to this memory range via muMemAdvise as described below:
  • If MU_MEM_ADVISE_SET_READ_MOSTLY was set on any subset of this memory range, then that subset will create a read-only copy of the pages on dstDevice.
  • If MU_MEM_ADVISE_SET_PREFERRED_LOCATION was called on any subset of this memory range, then the pages will be migrated to dstDevice even if dstDevice is not the preferred location of any pages in the memory range.
  • If MU_MEM_ADVISE_SET_ACCESSED_BY was called on any subset of this memory range, then mappings to those pages from all the appropriate processors are updated to refer to the new location if establishing such a mapping is possible. Otherwise, those mappings are cleared.
  • Note that this API is not required for functionality and only serves to improve performance by allowing the application to migrate data to a suitable location before it is accessed. Memory accesses to this range are always coherent and are allowed even when the data is actively being migrated.
  • Note that this function is asynchronous with respect to the host and all work on other devices.

Parameters

  • devPtr (MUdeviceptr): Pointer to be prefetched
  • count (size_t): Size in bytes
  • dstDevice (MUdevice): Destination device to prefetch to
  • hStream (MUstream): Stream to enqueue prefetch operation

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemPrefetchAsync_v2​

MUresult muMemPrefetchAsync_v2(MUdeviceptr devPtr, size_t count, MUmemLocation location, unsigned int flags, MUstream hStream)

Description

  • Prefetches memory to the specified destination location.
  • Prefetches memory to the specified destination location. devPtr is the base device pointer of the memory to be prefetched and location specifies the destination location. count specifies the number of bytes to copy. hStream is the stream in which the operation is enqueued. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables.
  • Specifying MU_MEM_LOCATION_TYPE_DEVICE for MUmemLocation::type will prefetch memory to GPU specified by device ordinal MUmemLocation::id which must have non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Additionally, hStream must be associated with a device that has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Specifying MU_MEM_LOCATION_TYPE_HOST as MUmemLocation::type will prefetch data to host memory. Applications can request prefetching memory to a specific host NUMA node by specifying MU_MEM_LOCATION_TYPE_HOST_NUMA for MUmemLocation::type and a valid host NUMA node id in MUmemLocation::id Users can also request prefetching memory to the host NUMA node closest to the current thread's CPU by specifying MU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT for MUmemLocation::type. Note when MUmemLocation::type is etiher MU_MEM_LOCATION_TYPE_HOST OR MU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT, MUmemLocation::id will be ignored.
  • The start address and end address of the memory range will be rounded down and rounded up respectively to be aligned to CPU page size before the prefetch operation is enqueued in the stream.
  • If no physical memory has been allocated for this region, then this memory region will be populated and mapped on the destination device. If there's insufficient memory to prefetch the desired region, the Unified Memory driver may evict pages from other muMemAllocManaged allocations to host memory in order to make room. Device memory allocated using muMemAlloc or muArrayCreate will not be evicted.
  • By default, any mappings to the previous location of the migrated pages are removed and mappings for the new location are only setup on the destination location. The exact behavior however also depends on the settings applied to this memory range via muMemAdvise as described below:
  • If MU_MEM_ADVISE_SET_READ_MOSTLY was set on any subset of this memory range, then that subset will create a read-only copy of the pages on destination location. If however the destination location is a host NUMA node, then any pages of that subset that are already in another host NUMA node will be transferred to the destination.
  • If MU_MEM_ADVISE_SET_PREFERRED_LOCATION was called on any subset of this memory range, then the pages will be migrated to location even if location is not the preferred location of any pages in the memory range.
  • If MU_MEM_ADVISE_SET_ACCESSED_BY was called on any subset of this memory range, then mappings to those pages from all the appropriate processors are updated to refer to the new location if establishing such a mapping is possible. Otherwise, those mappings are cleared.
  • Note that this API is not required for functionality and only serves to improve performance by allowing the application to migrate data to a suitable location before it is accessed. Memory accesses to this range are always coherent and are allowed even when the data is actively being migrated.
  • Note that this function is asynchronous with respect to the host and all work on other devices.

Parameters

  • devPtr (MUdeviceptr): Pointer to be prefetched
  • count (size_t): Size in bytes
  • location (MUmemLocation)
  • flags (unsigned int): flags for future use, must be zero now.
  • hStream (MUstream): Stream to enqueue prefetch operation

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemAdvise​

MUresult muMemAdvise(MUdeviceptr devPtr, size_t count, MUmem_advise advice, MUdevice device)

Description

  • Advise about the usage of a given memory range.
  • Note there is a later version of this API, muMemAdvise_v2. It will supplant this version in 13.0, which is retained for minor version compatibility.
  • Advise the Unified Memory subsystem about the usage pattern for the memory range starting at devPtr with a size of count bytes. The start address and end address of the memory range will be rounded down and rounded up respectively to be aligned to CPU page size before the advice is applied. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables. The memory range could also refer to system-allocated pageable memory provided it represents a valid, host-accessible region of memory and all additional constraints imposed by advice as outlined below are also satisfied. Specifying an invalid system-allocated pageable memory range results in an error being returned.
  • The advice parameter can take the following values: MU_MEM_ADVISE_SET_READ_MOSTLY: This implies that the data is mostly going to be read from and only occasionally written to. Any read accesses from any processor to this region will create a read-only copy of at least the accessed pages in that processor's memory. Additionally, if muMemPrefetchAsync is called on this region, it will create a read-only copy of the data on the destination processor. If any processor writes to this region, all copies of the corresponding page will be invalidated except for the one where the write occurred. The device argument is ignored for this advice. Note that for a page to be read-duplicated, the accessing processor must either be the CPU or a GPU that has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Also, if a context is created on a device that does not have the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS set, then read-duplication will not occur until all such contexts are destroyed. If the memory region refers to valid system-allocated pageable memory, then the accessing device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS for a read-only copy to be created on that device. Note however that if the accessing device also has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then setting this advice will not create a read-only copy when that device accesses this memory region. MU_MEM_ADVISE_UNSET_READ_MOSTLY: Undoes the effect of MU_MEM_ADVISE_SET_READ_MOSTLY and also prevents the Unified Memory driver from attempting heuristic read-duplication on the memory range. Any read-duplicated copies of the data will be collapsed into a single copy. The location for the collapsed copy will be the preferred location if the page has a preferred location and one of the read-duplicated copies was resident at that location. Otherwise, the location chosen is arbitrary. MU_MEM_ADVISE_SET_PREFERRED_LOCATION: This advice sets the preferred location for the data to be the memory belonging to device. Passing in MU_DEVICE_CPU for device sets the preferred location as host memory. If device is a GPU, then it must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Setting the preferred location does not cause data to migrate to that location immediately. Instead, it guides the migration policy when a fault occurs on that memory region. If the data is already in its preferred location and the faulting processor can establish a mapping without requiring the data to be migrated, then data migration will be avoided. On the other hand, if the data is not in its preferred location or if a direct mapping cannot be established, then it will be migrated to the processor accessing it. It is important to note that setting the preferred location does not prevent data prefetching done using muMemPrefetchAsync. Having a preferred location can override the page thrash detection and resolution logic in the Unified Memory driver. Normally, if a page is detected to be constantly thrashing between for example host and device memory, the page may eventually be pinned to host memory by the Unified Memory driver. But if the preferred location is set as device memory, then the page will continue to thrash indefinitely. If MU_MEM_ADVISE_SET_READ_MOSTLY is also set on this memory region or any subset of it, then the policies associated with that advice will override the policies of this advice, unless read accesses from device will not result in a read-only copy being created on that device as outlined in description for the advice MU_MEM_ADVISE_SET_READ_MOSTLY. If the memory region refers to valid system-allocated pageable memory, then device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. MU_MEM_ADVISE_UNSET_PREFERRED_LOCATION: Undoes the effect of MU_MEM_ADVISE_SET_PREFERRED_LOCATION and changes the preferred location to none. MU_MEM_ADVISE_SET_ACCESSED_BY: This advice implies that the data will be accessed by device. Passing in MU_DEVICE_CPU for device will set the advice for the CPU. If device is a GPU, then the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS must be non-zero. This advice does not cause data migration and has no impact on the location of the data per se. Instead, it causes the data to always be mapped in the specified processor's page tables, as long as the location of the data permits a mapping to be established. If the data gets migrated for any reason, the mappings are updated accordingly. This advice is recommended in scenarios where data locality is not important, but avoiding faults is. Consider for example a system containing multiple GPUs with peer-to-peer access enabled, where the data located on one GPU is occasionally accessed by peer GPUs. In such scenarios, migrating data over to the other GPUs is not as important because the accesses are infrequent and the overhead of migration may be too high. But preventing faults can still help improve performance, and so having a mapping set up in advance is useful. Note that on CPU access of this data, the data may be migrated to host memory because the CPU typically cannot access device memory directly. Any GPU that had the MU_MEM_ADVISE_SET_ACCESSED_BY flag set for this data will now have its mapping updated to point to the page in host memory. If MU_MEM_ADVISE_SET_READ_MOSTLY is also set on this memory region or any subset of it, then the policies associated with that advice will override the policies of this advice. Additionally, if the preferred location of this memory region or any subset of it is also device, then the policies associated with MU_MEM_ADVISE_SET_PREFERRED_LOCATION will override the policies of this advice. If the memory region refers to valid system-allocated pageable memory, then device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. Additionally, if device has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then this call has no effect. MU_MEM_ADVISE_UNSET_ACCESSED_BY: Undoes the effect of MU_MEM_ADVISE_SET_ACCESSED_BY. Any mappings to the data from device may be removed at any time causing accesses to result in non-fatal page faults. If the memory region refers to valid system-allocated pageable memory, then device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. Additionally, if device has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then this call has no effect.

Parameters

  • devPtr (MUdeviceptr): Pointer to memory to set the advice for
  • count (size_t): Size in bytes of the memory range
  • advice (MUmem_advise): Advice to be applied for the specified memory range
  • device (MUdevice): Device to apply the advice for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemAdvise_v2​

MUresult muMemAdvise_v2(MUdeviceptr devPtr, size_t count, MUmem_advise advice, MUmemLocation location)

Description

  • Advise about the usage of a given memory range.
  • Advise the Unified Memory subsystem about the usage pattern for the memory range starting at devPtr with a size of count bytes. The start address and end address of the memory range will be rounded down and rounded up respectively to be aligned to CPU page size before the advice is applied. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables. The memory range could also refer to system-allocated pageable memory provided it represents a valid, host-accessible region of memory and all additional constraints imposed by advice as outlined below are also satisfied. Specifying an invalid system-allocated pageable memory range results in an error being returned.
  • The advice parameter can take the following values: MU_MEM_ADVISE_SET_READ_MOSTLY: This implies that the data is mostly going to be read from and only occasionally written to. Any read accesses from any processor to this region will create a read-only copy of at least the accessed pages in that processor's memory. Additionally, if muMemPrefetchAsync or muMemPrefetchAsync_v2 is called on this region, it will create a read-only copy of the data on the destination processor. If the target location for muMemPrefetchAsync_v2 is a host NUMA node and a read-only copy already exists on another host NUMA node, that copy will be migrated to the targeted host NUMA node. If any processor writes to this region, all copies of the corresponding page will be invalidated except for the one where the write occurred. If the writing processor is the CPU and the preferred location of the page is a host NUMA node, then the page will also be migrated to that host NUMA node. The location argument is ignored for this advice. Note that for a page to be read-duplicated, the accessing processor must either be the CPU or a GPU that has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Also, if a context is created on a device that does not have the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS set, then read-duplication will not occur until all such contexts are destroyed. If the memory region refers to valid system-allocated pageable memory, then the accessing device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS for a read-only copy to be created on that device. Note however that if the accessing device also has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then setting this advice will not create a read-only copy when that device accesses this memory region. MU_MEM_ADVISE_UNSET_READ_MOSTLY: Undoes the effect of MU_MEM_ADVISE_SET_READ_MOSTLY and also prevents the Unified Memory driver from attempting heuristic read-duplication on the memory range. Any read-duplicated copies of the data will be collapsed into a single copy. The location for the collapsed copy will be the preferred location if the page has a preferred location and one of the read-duplicated copies was resident at that location. Otherwise, the location chosen is arbitrary. Note: The location argument is ignored for this advice. MU_MEM_ADVISE_SET_PREFERRED_LOCATION: This advice sets the preferred location for the data to be the memory belonging to location. When MUmemLocation::type is MU_MEM_LOCATION_TYPE_HOST, MUmemLocation::id is ignored and the preferred location is set to be host memory. To set the preferred location to a specific host NUMA node, applications must set MUmemLocation::type to MU_MEM_LOCATION_TYPE_HOST_NUMA and MUmemLocation::id must specify the NUMA ID of the host NUMA node. If MUmemLocation::type is set to MU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT, MUmemLocation::id will be ignored and the the host NUMA node closest to the calling thread's CPU will be used as the preferred location. If MUmemLocation::type is a MU_MEM_LOCATION_TYPE_DEVICE, then MUmemLocation::id must be a valid device ordinal and the device must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. Setting the preferred location does not cause data to migrate to that location immediately. Instead, it guides the migration policy when a fault occurs on that memory region. If the data is already in its preferred location and the faulting processor can establish a mapping without requiring the data to be migrated, then data migration will be avoided. On the other hand, if the data is not in its preferred location or if a direct mapping cannot be established, then it will be migrated to the processor accessing it. It is important to note that setting the preferred location does not prevent data prefetching done using muMemPrefetchAsync. Having a preferred location can override the page thrash detection and resolution logic in the Unified Memory driver. Normally, if a page is detected to be constantly thrashing between for example host and device memory, the page may eventually be pinned to host memory by the Unified Memory driver. But if the preferred location is set as device memory, then the page will continue to thrash indefinitely. If MU_MEM_ADVISE_SET_READ_MOSTLY is also set on this memory region or any subset of it, then the policies associated with that advice will override the policies of this advice, unless read accesses from location will not result in a read-only copy being created on that procesor as outlined in description for the advice MU_MEM_ADVISE_SET_READ_MOSTLY. If the memory region refers to valid system-allocated pageable memory, and MUmemLocation::type is MU_MEM_LOCATION_TYPE_DEVICE then MUmemLocation::id must be a valid device that has a non-zero alue for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. MU_MEM_ADVISE_UNSET_PREFERRED_LOCATION: Undoes the effect of MU_MEM_ADVISE_SET_PREFERRED_LOCATION and changes the preferred location to none. The location argument is ignored for this advice. MU_MEM_ADVISE_SET_ACCESSED_BY: This advice implies that the data will be accessed by processor location. The MUmemLocation::type must be either MU_MEM_LOCATION_TYPE_DEVICE with MUmemLocation::id representing a valid device ordinal or MU_MEM_LOCATION_TYPE_HOST and MUmemLocation::id will be ignored. All other location types are invalid. If MUmemLocation::id is a GPU, then the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS must be non-zero. This advice does not cause data migration and has no impact on the location of the data per se. Instead, it causes the data to always be mapped in the specified processor's page tables, as long as the location of the data permits a mapping to be established. If the data gets migrated for any reason, the mappings are updated accordingly. This advice is recommended in scenarios where data locality is not important, but avoiding faults is. Consider for example a system containing multiple GPUs with peer-to-peer access enabled, where the data located on one GPU is occasionally accessed by peer GPUs. In such scenarios, migrating data over to the other GPUs is not as important because the accesses are infrequent and the overhead of migration may be too high. But preventing faults can still help improve performance, and so having a mapping set up in advance is useful. Note that on CPU access of this data, the data may be migrated to host memory because the CPU typically cannot access device memory directly. Any GPU that had the MU_MEM_ADVISE_SET_ACCESSED_BY flag set for this data will now have its mapping updated to point to the page in host memory. If MU_MEM_ADVISE_SET_READ_MOSTLY is also set on this memory region or any subset of it, then the policies associated with that advice will override the policies of this advice. Additionally, if the preferred location of this memory region or any subset of it is also location, then the policies associated with MU_MEM_ADVISE_SET_PREFERRED_LOCATION will override the policies of this advice. If the memory region refers to valid system-allocated pageable memory, and MUmemLocation::type is MU_MEM_LOCATION_TYPE_DEVICE then device in MUmemLocation::id must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. Additionally, if MUmemLocation::id has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then this call has no effect. MU_MEM_ADVISE_UNSET_ACCESSED_BY: Undoes the effect of MU_MEM_ADVISE_SET_ACCESSED_BY. Any mappings to the data from location may be removed at any time causing accesses to result in non-fatal page faults. If the memory region refers to valid system-allocated pageable memory, and MUmemLocation::type is MU_MEM_LOCATION_TYPE_DEVICE then device in MUmemLocation::id must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. Additionally, if MUmemLocation::id has a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS_USES_HOST_PAGE_TABLES, then this call has no effect.

Parameters

  • devPtr (MUdeviceptr): Pointer to memory to set the advice for
  • count (size_t): Size in bytes of the memory range
  • advice (MUmem_advise): Advice to be applied for the specified memory range
  • location (MUmemLocation): location to apply the advice for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemRangeGetAttribute​

MUresult muMemRangeGetAttribute(void *data, size_t dataSize, MUmem_range_attribute attribute, MUdeviceptr devPtr, size_t count)

Description

  • Performs a batch of memory prefetches asynchronously.
  • Performs a batch of memory prefetches. The batch as a whole executes in stream order but operations within a batch are not guaranteed to execute in any specific order. All devices in the system must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS otherwise the API will return an error.
  • The semantics of the individual prefetch operations are as described in muMemPrefetchAsync.
  • Performs memory prefetch on address ranges specified in dptrs and sizes. Both arrays must be of the same length as specified by count. Each memory range specified must refer to managed memory allocated via muMemAllocManaged or declared via managed variables or it may also refer to system-allocated memory when all devices have a non-zero value for MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. The prefetch location for every operation in the batch is specified in the prefetchLocs array. Each entry in this array can apply to more than one operation. This can be done by specifying in the prefetchLocIdxs array, the index of the first prefetch operation that the corresponding entry in the prefetchLocs array applies to. Both prefetchLocs and prefetchLocIdxs must be of the same length as specified by numPrefetchLocs. For example, if a batch has 10 prefetches listed in dptrs/sizes, the first 4 of which are to be prefetched to one location and the remaining 6 are to be prefetched to another, then numPrefetchLocs will be 2, prefetchLocIdxs will be {0, 4} and prefetchLocs will contain the two locations. Note the first entry in prefetchLocIdxs must always be 0. Also, each entry must be greater than the previous entry and the last entry should be less than count. Furthermore, numPrefetchLocs must be lesser than or equal to count.
  • Performs a batch of memory discards. The batch as a whole executes in stream order but operations within a batch are not guaranteed to execute in any specific order. All devices in the system must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS otherwise the API will return an error.
  • Discarding a memory range informs the driver that the contents of that range are no longer useful. Discarding memory ranges allows the driver to optimize certain data migrations and can also help reduce memory pressure. This operation can be undone on any part of the range by either writing to it or prefetching it via muMemPrefetchAsync or muMemPrefetchBatchAsync. Reading from a discarded range, without a subsequent write or prefetch to that part of the range, will return an indeterminate value. Note that any reads, writes or prefetches to any part of the memory range that occur simultaneously with the discard operation result in undefined behavior.
  • Performs memory discard on address ranges specified in dptrs and sizes. Both arrays must be of the same length as specified by count. Each memory range specified must refer to managed memory allocated via muMemAllocManaged or declared via managed variables or it may also refer to system-allocated memory when all devices have a non-zero value for MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS.
  • Performs a batch of memory discards followed by prefetches. The batch as a whole executes in stream order but operations within a batch are not guaranteed to execute in any specific order. All devices in the system must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS otherwise the API will return an error.
  • Calling muMemDiscardAndPrefetchBatchAsync is semantically equivalent to calling muMemDiscardBatchAsync followed by muMemPrefetchBatchAsync, but is more optimal. For more details on what discarding and prefetching imply, please refer to muMemDiscardBatchAsync and muMemPrefetchBatchAsync respectively. Note that any reads, writes or prefetches to any part of the memory range that occur simultaneously with this combined discard+prefetch operation result in undefined behavior.
  • Performs memory discard and prefetch on address ranges specified in dptrs and sizes. Both arrays must be of the same length as specified by count. Each memory range specified must refer to managed memory allocated via muMemAllocManaged or declared via managed variables or it may also refer to system-allocated memory when all devices have a non-zero value for MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS. Every operation in the batch has to be associated with a valid location to prefetch the address range to and specified in the prefetchLocs array. Each entry in this array can apply to more than one operation. This can be done by specifying in the prefetchLocIdxs array, the index of the first operation that the corresponding entry in the prefetchLocs array applies to. Both prefetchLocs and prefetchLocIdxs must be of the same length as specified by numPrefetchLocs. For example, if a batch has 10 operations listed in dptrs/sizes, the first 6 of which are to be prefetched to one location and the remaining 4 are to be prefetched to another, then numPrefetchLocs will be 2, prefetchLocIdxs will be {0, 6} and prefetchLocs will contain the two set of locations. Note the first entry in prefetchLocIdxs must always be 0. Also, each entry must be greater than the previous entry and the last entry should be less than count. Furthermore, numPrefetchLocs must be lesser than or equal to count.
  • Query an attribute about the memory range starting at devPtr with a size of count bytes. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables.
  • The attribute parameter can take the following values: MU_MEM_RANGE_ATTRIBUTE_READ_MOSTLY: If this attribute is specified, data will be interpreted as a 32-bit integer, and dataSize must be 4. The result returned will be 1 if all pages in the given memory range have read-duplication enabled, or 0 otherwise. MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION: If this attribute is specified, data will be interpreted as a 32-bit integer, and dataSize must be 4. The result returned will be a GPU device id if all pages in the memory range have that GPU as their preferred location, or it will be MU_DEVICE_CPU if all pages in the memory range have the CPU as their preferred location, or it will be MU_DEVICE_INVALID if either all the pages don't have the same preferred location or some of the pages don't have a preferred location at all. Note that the actual location of the pages in the memory range at the time of the query may be different from the preferred location. MU_MEM_RANGE_ATTRIBUTE_ACCESSED_BY: If this attribute is specified, data will be interpreted as an array of 32-bit integers, and dataSize must be a non-zero multiple of 4. The result returned will be a list of device ids that had MU_MEM_ADVISE_SET_ACCESSED_BY set for that entire memory range. If any device does not have that advice set for the entire memory range, that device will not be included. If data is larger than the number of devices that have that advice set for that memory range, MU_DEVICE_INVALID will be returned in all the extra space provided. For ex., if dataSize is 12 (i.e. data has 3 elements) and only device 0 has the advice set, then the result returned will be { 0, MU_DEVICE_INVALID, MU_DEVICE_INVALID }. If data is smaller than the number of devices that have that advice set, then only as many devices will be returned as can fit in the array. There is no guarantee on which specific devices will be returned, however. MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION: If this attribute is specified, data will be interpreted as a 32-bit integer, and dataSize must be 4. The result returned will be the last location to which all pages in the memory range were prefetched explicitly via muMemPrefetchAsync. This will either be a GPU id or MU_DEVICE_CPU depending on whether the last location for prefetch was a GPU or the CPU respectively. If any page in the memory range was never explicitly prefetched or if all pages were not prefetched to the same location, MU_DEVICE_INVALID will be returned. Note that this simply returns the last location that the application requested to prefetch the memory range to. It gives no indication as to whether the prefetch operation to that location has completed or even begun. MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION_TYPE: If this attribute is specified, data will be interpreted as a MUmemLocationType, and dataSize must be sizeof(MUmemLocationType). The MUmemLocationType returned will be MU_MEM_LOCATION_TYPE_DEVICE if all pages in the memory range have the same GPU as their preferred location, or MUmemLocationType will be MU_MEM_LOCATION_TYPE_HOST if all pages in the memory range have the CPU as their preferred location, or it will be MU_MEM_LOCATION_TYPE_HOST_NUMA if all the pages in the memory range have the same host NUMA node ID as their preferred location or it will be MU_MEM_LOCATION_TYPE_INVALID if either all the pages don't have the same preferred location or some of the pages don't have a preferred location at all. Note that the actual location type of the pages in the memory range at the time of the query may be different from the preferred location type. MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION_ID: If this attribute is specified, data will be interpreted as a 32-bit integer, and dataSize must be 4. If the MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION_TYPE query for the same address range returns MU_MEM_LOCATION_TYPE_DEVICE, it will be a valid device ordinal or if it returns MU_MEM_LOCATION_TYPE_HOST_NUMA, it will be a valid host NUMA node ID or if it returns any other location type, the id should be ignored. MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION_TYPE: If this attribute is specified, data will be interpreted as a MUmemLocationType, and dataSize must be sizeof(MUmemLocationType). The result returned will be the last location to which all pages in the memory range were prefetched explicitly via muMemPrefetchAsync. The MUmemLocationType returned will be MU_MEM_LOCATION_TYPE_DEVICE if the last prefetch location was a GPU or MU_MEM_LOCATION_TYPE_HOST if it was the CPU or MU_MEM_LOCATION_TYPE_HOST_NUMA if the last prefetch location was a specific host NUMA node. If any page in the memory range was never explicitly prefetched or if all pages were not prefetched to the same location, MUmemLocationType will be MU_MEM_LOCATION_TYPE_INVALID. Note that this simply returns the last location type that the application requested to prefetch the memory range to. It gives no indication as to whether the prefetch operation to that location has completed or even begun. MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION_ID: If this attribute is specified, data will be interpreted as a 32-bit integer, and dataSize must be 4. If the MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION_TYPE query for the same address range returns MU_MEM_LOCATION_TYPE_DEVICE, it will be a valid device ordinal or if it returns MU_MEM_LOCATION_TYPE_HOST_NUMA, it will be a valid host NUMA node ID or if it returns any other location type, the id should be ignored.

Parameters

  • data (void *): A pointers to a memory location where the result of each attribute query will be written to.
  • dataSize (size_t): Array containing the size of data
  • attribute (MUmem_range_attribute): The attribute to query
  • devPtr (MUdeviceptr): Start of the range to query
  • count (size_t): Size of the range to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

See also

muMemRangeGetAttributes​

MUresult muMemRangeGetAttributes(void **data, size_t *dataSizes, MUmem_range_attribute *attributes, size_t numAttributes, MUdeviceptr devPtr, size_t count)

Description

  • Query attributes of a given memory range.
  • Query attributes of the memory range starting at devPtr with a size of count bytes. The memory range must refer to managed memory allocated via muMemAllocManaged or declared via managed variables. The attributes array will be interpreted to have numAttributes entries. The dataSizes array will also be interpreted to have numAttributes entries. The results of the query will be stored in data.
  • The list of supported attributes are given below. Please refer to muMemRangeGetAttribute for attribute descriptions and restrictions.
  • MU_MEM_RANGE_ATTRIBUTE_READ_MOSTLY MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION MU_MEM_RANGE_ATTRIBUTE_ACCESSED_BY MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION_TYPE MU_MEM_RANGE_ATTRIBUTE_PREFERRED_LOCATION_ID MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION_TYPE MU_MEM_RANGE_ATTRIBUTE_LAST_PREFETCH_LOCATION_ID

Parameters

  • data (void **): A two-dimensional array containing pointers to memory locations where the result of each attribute query will be written to.
  • dataSizes (size_t *): Array containing the sizes of each result
  • attributes (MUmem_range_attribute *): An array of attributes to query (numAttributes and the number of attributes in this array should match)
  • numAttributes (size_t): Number of attributes to query
  • devPtr (MUdeviceptr): Start of the range to query
  • count (size_t): Size of the range to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muPointerSetAttribute​

MUresult muPointerSetAttribute(const void *value, MUpointer_attribute attribute, MUdeviceptr ptr)

Description

  • Set attributes on a previously allocated memory region.
  • The supported attributes are:
  • MU_POINTER_ATTRIBUTE_SYNC_MEMOPS: A boolean attribute that can either be set (1) or unset (0). When set, the region of memory that ptr points to is guaranteed to always synchronize memory operations that are synchronous. If there are some previously initiated synchronous memory operations that are pending when this attribute is set, the function does not return until those memory operations are complete. See further documentation in the section titled "API synchronization behavior" to learn more about cases when synchronous memory operations can exhibit asynchronous behavior. value will be considered as a pointer to an unsigned integer to which this attribute is to be set.

Parameters

  • value (const void *): Pointer to memory containing the value to be set
  • attribute (MUpointer_attribute): Pointer attribute to set
  • ptr (MUdeviceptr): Pointer to a memory region allocated using MUSA memory allocation APIs

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muPointerGetAttributes​

MUresult muPointerGetAttributes(unsigned int numAttributes, MUpointer_attribute *attributes, void **data, MUdeviceptr ptr)

Description

  • Returns information about a pointer.
  • The supported attributes are (refer to muPointerGetAttribute for attribute descriptions and restrictions):
  • MU_POINTER_ATTRIBUTE_CONTEXT MU_POINTER_ATTRIBUTE_MEMORY_TYPE MU_POINTER_ATTRIBUTE_DEVICE_POINTER MU_POINTER_ATTRIBUTE_HOST_POINTER MU_POINTER_ATTRIBUTE_SYNC_MEMOPS MU_POINTER_ATTRIBUTE_BUFFER_ID MU_POINTER_ATTRIBUTE_IS_MANAGED MU_POINTER_ATTRIBUTE_DEVICE_ORDINAL MU_POINTER_ATTRIBUTE_RANGE_START_ADDR MU_POINTER_ATTRIBUTE_RANGE_SIZE MU_POINTER_ATTRIBUTE_MAPPED MU_POINTER_ATTRIBUTE_IS_LEGACY_MUSA_IPC_CAPABLE MU_POINTER_ATTRIBUTE_ALLOWED_HANDLE_TYPES MU_POINTER_ATTRIBUTE_MEMPOOL_HANDLE MU_POINTER_ATTRIBUTE_IS_HW_DECOMPRESS_CAPABLE
  • If ptr was not allocated by, mapped by, or registered with a MUcontext which uses UVA (Unified Virtual Addressing), MUSA_ERROR_INVALID_CONTEXT is returned.

Parameters

  • numAttributes (unsigned int): Number of attributes to query
  • attributes (MUpointer_attribute *): An array of attributes to query (numAttributes and the number of attributes in this array should match)
  • data (void **): A two-dimensional array containing pointers to memory locations where the result of each attribute query will be written to.
  • ptr (MUdeviceptr): Pointer to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.16 Stream Management​

muStreamCreate​

MUresult muStreamCreate(MUstream *phStream, unsigned int Flags)

Description

  • Create a stream.
  • Creates a stream and returns a handle in phStream. The Flags argument determines behaviors of the stream.
  • Valid values for Flags are: MU_STREAM_DEFAULT: Default stream creation flag. MU_STREAM_NON_BLOCKING: Specifies that work running in the created stream may run concurrently with work in stream 0 (the NULL stream), and that the created stream should perform no implicit synchronization with stream 0.

Parameters

  • phStream (MUstream *): Returned newly created stream
  • Flags (unsigned int): Parameters for stream creation

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamCreateWithPriority​

MUresult muStreamCreateWithPriority(MUstream *phStream, unsigned int flags, int priority)

Description

  • Create a stream with the given priority.
  • Creates a stream with the specified priority and returns a handle in phStream. This affects the scheduling priority of work in the stream. Priorities provide a hint to preferentially run work with higher priority when possible, but do not preempt already-running work or provide any other functional guarantee on execution order.
  • priority follows a convention where lower numbers represent higher priorities. '0' represents default priority. The range of meaningful numerical priorities can be queried using muCtxGetStreamPriorityRange. If the specified priority is outside the numerical range returned by muCtxGetStreamPriorityRange, it will automatically be clamped to the lowest or the highest number in the range.

Parameters

  • phStream (MUstream *): Returned newly created stream
  • flags (unsigned int): Flags for stream creation. See muStreamCreate for a list of valid flags
  • priority (int): Stream priority. Lower numbers represent higher priorities. See muCtxGetStreamPriorityRange for more information about meaningful stream priorities that can be passed.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.
  • Stream priorities are supported only on GPUs with compute capability 3.5 or higher.
  • In the current implementation, only compute kernels launched in priority streams are affected by the stream's priority. Stream priorities have no effect on host-to-device and device-to-host memory operations.

See also

muStreamGetPriority​

MUresult muStreamGetPriority(MUstream hStream, int *priority)

Description

  • Begins capture to CIG on a stream.
  • Begin CIG (MUSA in Graphics) capture on hStream for the graphics API as provided in streamCigCaptureParams. When a stream is in CIG capture mode, all operations pushed into the stream will not be executed, but will instead be captured into a graphics API command list/command buffer. All kernel launches and memory copy/memory set operations on the CIG stream will be recorded. When the command list is executed by the graphics API, all the stream's operations will execute in order along with other graphics API commands in the command list.
  • CIG stream capture may not be initiated if stream is MU_STREAM_LEGACY. Capture must be ended on the same stream in which it was initiated, and it may only be initiated if the stream is not already in CIG capture mode.
  • The context must be also created in CIG mode previously, otherwise this operation will fail and MUSA_ERROR_INVALID_CONTEXT will be returned.
  • Data from the graphics client can be shared with MUSA via the streamSharedData in streamCigCaptureParams. The format of streamSharedData is dependent on the type of the graphics client. For D3D12, streamSharedData is an ID3D12CommandList object pointer. The command list must be in ready state for recording commands whenever kernels are launched on the stream. The command list provided must belong to the graphics API device that the CIG context was created with, otherwise the behavior will be undefined.
  • The stream object may not be destroyed until its associated command list has finished executing on the GPU. The command list/command buffer used for capture may not be submitted for execution before a call to muStreamEndCaptureToCig is made on the associated stream.
  • Graphics resources to be accessed by work recorded on the CIG stream must use UAV barriers on the command list prior to recording work that accesses them on the stream.
  • Resubmission of the same recorded command list is not allowed. Further more, care must be taken for the order of execution of the recorded MUSA work with regards to other MUSA work submitted under the same CIG context. Out-of-order execution can lead to device hangs or exceptions.
  • CIG capture mode operates similarly to muStreamBeginCapture with the MU_STREAM_CAPTURE_MODE_RELAXED option. There are additional limitations to streams in CIG capture mode. The following functions are not allowed for CIG streams whether directly or indirectly via a recorded graph launch: muLaunchHostFunc muStreamAddCallback muStreamSynchronize muStreamWaitValue32 muStreamWaitValue64 muStreamBatchMemOp muStreamBeginCapture muStreamBeginCaptureToGraph muMemAllocAsync muMemFreeAsync
  • End CIG capture on hStream. Capture must have been initiated on hStream via a call to muStreamBeginCaptureToCig. Once this function is called, hStream will exit CIG capture mode and return to its original state, thus removing all CIG stream restrictions. Also, the command list/command buffer that was associated with hStream in the previous call to muStreamBeginCaptureToCig is now allowed to be submitted for execution on the graphics API. However, the stream may not be destroyed until execution of the command list is fully done on the GPU. This requirements extends also to all streams dependant on the CIG stream (e.g. via event waits).
  • Query the priority of a stream created using muStreamCreate, muStreamCreateWithPriority or muGreenCtxStreamCreate and return the priority in priority. Note that if the stream was created with a priority outside the numerical range returned by muCtxGetStreamPriorityRange, this function returns the clamped priority. See muStreamCreateWithPriority for details about priority clamping.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • priority (int *): Pointer to a signed integer in which the stream's priority is returned

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_WRONG_THREAD
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muStreamGetPriority_ptsz.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetDevice​

MUresult muStreamGetDevice(MUstream hStream, MUdevice *device)

Description

  • Returns the device handle of the stream.
  • Returns in *device the device handle of the stream

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • device (MUdevice *): Returns the device to which a stream belongs

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muStreamGetDevice_ptsz.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetFlags​

MUresult muStreamGetFlags(MUstream hStream, unsigned int *flags)

Description

  • Query the flags of a given stream.
  • Query the flags of a stream created using muStreamCreate, muStreamCreateWithPriority or muGreenCtxStreamCreate and return the flags in flags.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • flags (unsigned int *): Pointer to an unsigned integer in which the stream's flags are returned The value returned in flags is a logical 'OR' of all flags that were used while creating this stream. See muStreamCreate for the list of valid flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • Additional exported symbol names in scope: muStreamGetFlags_ptsz.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetId​

MUresult muStreamGetId(MUstream hStream, unsigned long long *streamId)

Description

  • Returns the unique Id associated with the stream handle supplied.
  • Returns in streamId the unique Id which is associated with the given stream handle. The Id is unique for the life of the program.
  • The stream handle hStream can refer to any of the following: a stream created via any of the MUSA driver APIs such as muStreamCreate and muStreamCreateWithPriority, or their runtime API equivalents such as musaStreamCreate, musaStreamCreateWithFlags and musaStreamCreateWithPriority. Passing an invalid handle will result in undefined behavior. any of the special streams such as the NULL stream, MU_STREAM_LEGACY and MU_STREAM_PER_THREAD. The runtime API equivalents of these are also accepted, which are NULL, musaStreamLegacy and musaStreamPerThread respectively.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • streamId (unsigned long long *): Pointer to store the Id of the stream

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muStreamGetId_ptsz.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetCtx​

MUresult muStreamGetCtx(MUstream hStream, MUcontext *pctx)

Description

  • Query the context associated with a stream.
  • Returns the MUSA context that the stream is associated with.
  • Note there is a later version of this API, muStreamGetCtx_v2. It will supplant this version in MUSA 13.0. It is recommended to use muStreamGetCtx_v2 till then as this version will return MUSA_ERROR_NOT_SUPPORTED for streams created via the API muGreenCtxStreamCreate.
  • The stream handle hStream can refer to any of the following: a stream created via any of the MUSA driver APIs such as muStreamCreate and muStreamCreateWithPriority, or their runtime API equivalents such as musaStreamCreate, musaStreamCreateWithFlags and musaStreamCreateWithPriority. The returned context is the context that was active in the calling thread when the stream was created. Passing an invalid handle will result in undefined behavior. any of the special streams such as the NULL stream, MU_STREAM_LEGACY and MU_STREAM_PER_THREAD. The runtime API equivalents of these are also accepted, which are NULL, musaStreamLegacy and musaStreamPerThread respectively. Specifying any of the special handles will return the context current to the calling thread. If no context is current to the calling thread, MUSA_ERROR_INVALID_CONTEXT is returned.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • pctx (MUcontext *): Returned context associated with the stream

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamGetCtx_ptsz.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetCtx_v2​

MUresult muStreamGetCtx_v2(MUstream hStream, MUcontext *pCtx, MUgreenCtx *pGreenCtx)

Description

  • Query the contexts associated with a stream.
  • Returns the contexts that the stream is associated with.
  • If the stream is associated with a green context, the API returns the green context in pGreenCtx and the primary context of the associated device in pCtx.
  • If the stream is associated with a regular context, the API returns the regular context in pCtx and NULL in pGreenCtx.
  • The stream handle hStream can refer to any of the following: a stream created via any of the MUSA driver APIs such as muStreamCreate, muStreamCreateWithPriority and muGreenCtxStreamCreate, or their runtime API equivalents such as musaStreamCreate, musaStreamCreateWithFlags and musaStreamCreateWithPriority. Passing an invalid handle will result in undefined behavior. any of the special streams such as the NULL stream, MU_STREAM_LEGACY and MU_STREAM_PER_THREAD. The runtime API equivalents of these are also accepted, which are NULL, musaStreamLegacy and musaStreamPerThread respectively. If any of the special handles are specified, the API will operate on the context current to the calling thread. If a green context (that was converted via muCtxFromGreenCtx() before setting it current) is current to the calling thread, the API will return the green context in pGreenCtx and the primary context of the associated device in pCtx. If a regular context is current, the API returns the regular context in pCtx and NULL in pGreenCtx. Note that specifying MU_STREAM_PER_THREAD or musaStreamPerThread will return MUSA_ERROR_INVALID_HANDLE if a green context is current to the calling thread. If no context is current to the calling thread, MUSA_ERROR_INVALID_CONTEXT is returned.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • pCtx (MUcontext *): Returned regular context associated with the stream
  • pGreenCtx (MUgreenCtx *): Returned green context if the stream is associated with a green context or NULL if not

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamWaitEvent​

MUresult muStreamWaitEvent(MUstream hStream, MUevent hEvent, unsigned int Flags)

Description

  • Make a compute stream wait on an event.
  • Makes all future work submitted to hStream wait for all work captured in hEvent. See muEventRecord() for details on what is captured by an event. The synchronization will be performed efficiently on the device when applicable. hEvent may be from a different context or device than hStream.
  • flags include: MU_EVENT_WAIT_DEFAULT: Default event creation flag. MU_EVENT_WAIT_EXTERNAL: Event is captured in the graph as an external event node when performing stream capture. This flag is invalid outside of stream capture.

Parameters

  • hStream (MUstream): Stream to wait
  • hEvent (MUevent): Event to wait on (may not be NULL)
  • Flags (unsigned int): See MUevent_capture_flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muStreamWaitEvent_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muStreamAddCallback​

MUresult muStreamAddCallback(MUstream hStream, MUstreamCallback callback, void *userData, unsigned int flags)

Description

  • Add a callback to a compute stream.
  • The callback may be passed MUSA_SUCCESS or an error code. In the event of a device error, all subsequently executed callbacks will receive an appropriate MUresult.
  • Callbacks must not make any MUSA API calls. Attempting to use a MUSA API will result in MUSA_ERROR_NOT_PERMITTED. Callbacks must not perform any synchronization that may depend on outstanding device work or other callbacks that are not mandated to run earlier. Callbacks without a mandated order (in independent streams) execute in undefined order and may be serialized.
  • For the purposes of Unified Memory, callback execution makes a number of guarantees: The callback stream is considered idle for the duration of the callback. Thus, for example, a callback may always use memory attached to the callback stream. The start of execution of a callback has the same effect as synchronizing an event recorded in the same stream immediately prior to the callback. It thus synchronizes streams which have been "joined" prior to the callback. Adding device work to any stream does not have the effect of making the stream active until all preceding host functions and stream callbacks have executed. Thus, for example, a callback might use global attached memory even if work has been added to another stream, if the work has been ordered behind the callback with an event. Completion of a callback does not cause a stream to become active except as described above. The callback stream will remain idle if no device work follows the callback, and will remain idle across consecutive callbacks without device work in between. Thus, for example, stream synchronization can be done by signaling from a callback at the end of the stream.

Parameters

  • hStream (MUstream): Stream to add callback to
  • callback (MUstreamCallback): The function to call once preceding stream operations are complete
  • userData (void *): User specified data to be passed to the callback function
  • flags (unsigned int): Reserved for future use, must be 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamAddCallback_ptsz.
  • This function is slated for eventual deprecation and removal. If you do not require the callback to execute in case of a device error, consider using muLaunchHostFunc. Additionally, this function is not supported with muStreamBeginCapture and muStreamEndCapture, unlike muLaunchHostFunc.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muStreamBeginCapture​

MUresult muStreamBeginCapture(MUstream hStream, MUstreamCaptureMode mode)

Description

  • Begins graph capture on a stream.
  • Begin graph capture on hStream. When a stream is in capture mode, all operations pushed into the stream will not be executed, but will instead be captured into a graph, which will be returned via muStreamEndCapture. Capture may not be initiated if stream is MU_STREAM_LEGACY. Capture must be ended on the same stream in which it was initiated, and it may only be initiated if the stream is not already in capture mode. The capture mode may be queried via muStreamIsCapturing. A unique id representing the capture sequence may be queried via muStreamGetCaptureInfo.
  • If mode is not MU_STREAM_CAPTURE_MODE_RELAXED, muStreamEndCapture must be called on this stream from the same thread.

Parameters

  • hStream (MUstream): Stream in which to initiate capture
  • mode (MUstreamCaptureMode): Controls the interaction of this capture sequence with other API calls that are potentially unsafe. For more details see muThreadExchangeStreamCaptureMode.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muStreamBeginCapture_v2.
  • Kernels captured using this API must not use texture and surface references. Reading or writing through any texture or surface reference is undefined behavior. This restriction does not apply to texture and surface objects.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamBeginCaptureToGraph​

MUresult muStreamBeginCaptureToGraph(MUstream hStream, MUgraph hGraph, const MUgraphNode *dependencies, const MUgraphEdgeData *dependencyData, size_t numDependencies, MUstreamCaptureMode mode)

Description

  • Begins graph capture on a stream to an existing graph.
  • Begin graph capture on hStream, placing new nodes into an existing graph. When a stream is in capture mode, all operations pushed into the stream will not be executed, but will instead be captured into hGraph. The graph will not be instantiable until the user calls muStreamEndCapture.
  • Capture may not be initiated if stream is MU_STREAM_LEGACY. Capture must be ended on the same stream in which it was initiated, and it may only be initiated if the stream is not already in capture mode. The capture mode may be queried via muStreamIsCapturing. A unique id representing the capture sequence may be queried via muStreamGetCaptureInfo.
  • If mode is not MU_STREAM_CAPTURE_MODE_RELAXED, muStreamEndCapture must be called on this stream from the same thread.

Parameters

  • hStream (MUstream): Stream in which to initiate capture.
  • hGraph (MUgraph): Graph to capture into.
  • dependencies (const MUgraphNode *): Dependencies of the first node captured in the stream. Can be NULL if numDependencies is 0.
  • dependencyData (const MUgraphEdgeData *): Optional array of data associated with each dependency.
  • numDependencies (size_t): Number of dependencies.
  • mode (MUstreamCaptureMode): Controls the interaction of this capture sequence with other API calls that are potentially unsafe. For more details see muThreadExchangeStreamCaptureMode.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • Kernels captured using this API must not use texture and surface references. Reading or writing through any texture or surface reference is undefined behavior. This restriction does not apply to texture and surface objects.
  • This function may also return error codes from previous, asynchronous launches.

See also

muThreadExchangeStreamCaptureMode​

MUresult muThreadExchangeStreamCaptureMode(MUstreamCaptureMode *mode)

Description

  • Swaps the stream capture interaction mode for a thread.
  • Sets the calling thread's stream capture interaction mode to the value contained in *mode, and overwrites *mode with the previous mode for the thread. To facilitate deterministic behavior across function or module boundaries, callers are encouraged to use this API in a push-pop fashion:MUstreamCaptureModemode=desiredMode; muThreadExchangeStreamCaptureMode(&mode); ... muThreadExchangeStreamCaptureMode(&mode);//restorepreviousmode
  • During stream capture (see muStreamBeginCapture), some actions, such as a call to musaMalloc, may be unsafe. In the case of musaMalloc, the operation is not enqueued asynchronously to a stream, and is not observed by stream capture. Therefore, if the sequence of operations captured via muStreamBeginCapture depended on the allocation being replayed whenever the graph is launched, the captured graph would be invalid.
  • Therefore, stream capture places restrictions on API calls that can be made within or concurrently to a muStreamBeginCapture-muStreamEndCapture sequence. This behavior can be controlled via this API and flags to muStreamBeginCapture.
  • A thread's mode is one of the following: MU_STREAM_CAPTURE_MODE_GLOBAL: This is the default mode. If the local thread has an ongoing capture sequence that was not initiated with MU_STREAM_CAPTURE_MODE_RELAXED at muStreamBeginCapture, or if any other thread has a concurrent capture sequence initiated with MU_STREAM_CAPTURE_MODE_GLOBAL, this thread is prohibited from potentially unsafe API calls. MU_STREAM_CAPTURE_MODE_THREAD_LOCAL: If the local thread has an ongoing capture sequence not initiated with MU_STREAM_CAPTURE_MODE_RELAXED, it is prohibited from potentially unsafe API calls. Concurrent capture sequences in other threads are ignored. MU_STREAM_CAPTURE_MODE_RELAXED: The local thread is not prohibited from potentially unsafe API calls. Note that the thread is still prohibited from API calls which necessarily conflict with stream capture, for example, attempting muEventQuery on an event that was last recorded inside a capture sequence.

Parameters

  • mode (MUstreamCaptureMode *): Pointer to mode value to swap with the current mode

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamEndCapture​

MUresult muStreamEndCapture(MUstream hStream, MUgraph *phGraph)

Description

  • Ends capture on a stream, returning the captured graph.
  • End capture on hStream, returning the captured graph via phGraph. Capture must have been initiated on hStream via a call to muStreamBeginCapture. If capture was invalidated, due to a violation of the rules of stream capture, then a NULL graph will be returned.
  • If the mode argument to muStreamBeginCapture was not MU_STREAM_CAPTURE_MODE_RELAXED, this call must be from the same thread as muStreamBeginCapture.

Parameters

  • hStream (MUstream): Stream to query
  • phGraph (MUgraph *): The captured graph

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_WRONG_THREAD

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamIsCapturing​

MUresult muStreamIsCapturing(MUstream hStream, MUstreamCaptureStatus *captureStatus)

Description

  • Returns a stream's capture status.
  • Return the capture status of hStream via captureStatus. After a successful call, *captureStatus will contain one of the following: MU_STREAM_CAPTURE_STATUS_NONE: The stream is not capturing. MU_STREAM_CAPTURE_STATUS_ACTIVE: The stream is capturing. MU_STREAM_CAPTURE_STATUS_INVALIDATED: The stream was capturing but an error has invalidated the capture sequence. The capture sequence must be terminated with muStreamEndCapture on the stream where it was initiated in order to continue using hStream.
  • Note that, if this is called on MU_STREAM_LEGACY (the "null stream") while a blocking stream in the same context is capturing, it will return MUSA_ERROR_STREAM_CAPTURE_IMPLICIT and *captureStatus is unspecified after the call. The blocking stream capture is not invalidated.
  • When a blocking stream is capturing, the legacy stream is in an unusable state until the blocking stream capture is terminated. The legacy stream is not supported for stream capture, but attempted use would have an implicit dependency on the capturing stream(s).

Parameters

  • hStream (MUstream): Stream to query
  • captureStatus (MUstreamCaptureStatus *): Returns the stream's capture status

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_IMPLICIT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamGetCaptureInfo​

MUresult muStreamGetCaptureInfo(MUstream hStream, MUstreamCaptureStatus *captureStatus_out, muuint64_t *id_out, MUgraph *graph_out, const MUgraphNode **dependencies_out, size_t *numDependencies_out)

Description

  • Query a stream's capture state.
  • Query stream state related to stream capture.
  • If called on MU_STREAM_LEGACY (the "null stream") while a stream not created with MU_STREAM_NON_BLOCKING is capturing, returns MUSA_ERROR_STREAM_CAPTURE_IMPLICIT.
  • Valid data (other than capture status) is returned only if both of the following are true: the call returns MUSA_SUCCESS the returned capture status is MU_STREAM_CAPTURE_STATUS_ACTIVE

Parameters

  • hStream (MUstream): The stream to query
  • captureStatus_out (MUstreamCaptureStatus *): Location to return the capture status of the stream; required
  • id_out (muuint64_t *): Optional location to return an id for the capture sequence, which is unique over the lifetime of the process
  • graph_out (MUgraph *): Optional location to return the graph being captured into. All operations other than destroy and node removal are permitted on the graph while the capture sequence is in progress. This API does not transfer ownership of the graph, which is transferred or destroyed at muStreamEndCapture. Note that the graph handle may be invalidated before end of capture for certain errors. Nodes that are or become unreachable from the original stream at muStreamEndCapture due to direct actions on the graph do not trigger MUSA_ERROR_STREAM_CAPTURE_UNJOINED.
  • dependencies_out (const MUgraphNode **): Optional location to store a pointer to an array of nodes. The next node to be captured in the stream will depend on this set of nodes, absent operations such as event wait which modify this set. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated. The node handles may be copied out and are valid until they or the graph is destroyed. The driver-owned array may also be passed directly to APIs that operate on the graph (not the stream) without copying.
  • numDependencies_out (size_t *): Optional location to store the size of the array returned in dependencies_out.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_IMPLICIT

Note

  • Additional exported symbol names in scope: muStreamGetCaptureInfo_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muStreamGetCaptureInfo_v3​

MUresult muStreamGetCaptureInfo_v3(MUstream hStream, MUstreamCaptureStatus *captureStatus_out, muuint64_t *id_out, MUgraph *graph_out, const MUgraphNode **dependencies_out, const MUgraphEdgeData **edgeData_out, size_t *numDependencies_out)

Description

  • Query a stream's capture state (12.3+)
  • Query stream state related to stream capture.
  • If called on MU_STREAM_LEGACY (the "null stream") while a stream not created with MU_STREAM_NON_BLOCKING is capturing, returns MUSA_ERROR_STREAM_CAPTURE_IMPLICIT.
  • Valid data (other than capture status) is returned only if both of the following are true: the call returns MUSA_SUCCESS the returned capture status is MU_STREAM_CAPTURE_STATUS_ACTIVE
  • If edgeData_out is non-NULL then dependencies_out must be as well. If dependencies_out is non-NULL and edgeData_out is NULL, but there is non-zero edge data for one or more of the current stream dependencies, the call will return MUSA_ERROR_LOSSY_QUERY.

Parameters

  • hStream (MUstream): The stream to query
  • captureStatus_out (MUstreamCaptureStatus *): Location to return the capture status of the stream; required
  • id_out (muuint64_t *): Optional location to return an id for the capture sequence, which is unique over the lifetime of the process
  • graph_out (MUgraph *): Optional location to return the graph being captured into. All operations other than destroy and node removal are permitted on the graph while the capture sequence is in progress. This API does not transfer ownership of the graph, which is transferred or destroyed at muStreamEndCapture. Note that the graph handle may be invalidated before end of capture for certain errors. Nodes that are or become unreachable from the original stream at muStreamEndCapture due to direct actions on the graph do not trigger MUSA_ERROR_STREAM_CAPTURE_UNJOINED.
  • dependencies_out (const MUgraphNode **): Optional location to store a pointer to an array of nodes. The next node to be captured in the stream will depend on this set of nodes, absent operations such as event wait which modify this set. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated. The node handles may be copied out and are valid until they or the graph is destroyed. The driver-owned array may also be passed directly to APIs that operate on the graph (not the stream) without copying.
  • edgeData_out (const MUgraphEdgeData **): Optional location to store a pointer to an array of graph edge data. This array parallels dependencies_out; the next node to be added has an edge to dependencies_out[i] with annotation edgeData_out[i] for each i. The array pointer is valid until the next API call which operates on the stream or until the capture is terminated.
  • numDependencies_out (size_t *): Optional location to store the size of the array returned in dependencies_out.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_STREAM_CAPTURE_IMPLICIT, MUSA_ERROR_LOSSY_QUERY

Note

  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muStreamUpdateCaptureDependencies​

MUresult muStreamUpdateCaptureDependencies(MUstream hStream, MUgraphNode *dependencies, size_t numDependencies, unsigned int flags)

Description

  • Update the set of dependencies in a capturing stream (11.3+)
  • Modifies the dependency set of a capturing stream. The dependency set is the set of nodes that the next captured node in the stream will depend on.
  • Valid flags are MU_STREAM_ADD_CAPTURE_DEPENDENCIES and MU_STREAM_SET_CAPTURE_DEPENDENCIES. These control whether the set passed to the API is added to the existing set or replaces it. A flags value of 0 defaults to MU_STREAM_ADD_CAPTURE_DEPENDENCIES.
  • Nodes that are removed from the dependency set via this API do not result in MUSA_ERROR_STREAM_CAPTURE_UNJOINED if they are unreachable from the stream at muStreamEndCapture.
  • Returns MUSA_ERROR_ILLEGAL_STATE if the stream is not capturing.
  • This API is new in MUSA 11.3. Developers requiring compatibility across minor versions to MUSA 11.0 should not use this API or provide a fallback.

Parameters

  • hStream (MUstream): The stream to update
  • dependencies (MUgraphNode *): The set of dependencies to add
  • numDependencies (size_t): The size of the dependencies array
  • flags (unsigned int): See above

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_ILLEGAL_STATE

See also

muStreamUpdateCaptureDependencies_v2​

MUresult muStreamUpdateCaptureDependencies_v2(MUstream hStream, MUgraphNode *dependencies, const MUgraphEdgeData *dependencyData, size_t numDependencies, unsigned int flags)

Description

  • Update the set of dependencies in a capturing stream (12.3+)
  • Modifies the dependency set of a capturing stream. The dependency set is the set of nodes that the next captured node in the stream will depend on along with the edge data for those dependencies.
  • Valid flags are MU_STREAM_ADD_CAPTURE_DEPENDENCIES and MU_STREAM_SET_CAPTURE_DEPENDENCIES. These control whether the set passed to the API is added to the existing set or replaces it. A flags value of 0 defaults to MU_STREAM_ADD_CAPTURE_DEPENDENCIES.
  • Nodes that are removed from the dependency set via this API do not result in MUSA_ERROR_STREAM_CAPTURE_UNJOINED if they are unreachable from the stream at muStreamEndCapture.
  • Returns MUSA_ERROR_ILLEGAL_STATE if the stream is not capturing.

Parameters

  • hStream (MUstream): The stream to update
  • dependencies (MUgraphNode *): The set of dependencies to add
  • dependencyData (const MUgraphEdgeData *): Optional array of data associated with each dependency.
  • numDependencies (size_t): The size of the dependencies array
  • flags (unsigned int): See above

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_ILLEGAL_STATE

See also

muStreamAttachMemAsync​

MUresult muStreamAttachMemAsync(MUstream hStream, MUdeviceptr dptr, size_t length, unsigned int flags)

Description

  • Attach memory to a stream asynchronously.
  • Enqueues an operation in hStream to specify stream association of length bytes of memory starting from dptr. This function is a stream-ordered operation, meaning that it is dependent on, and will only take effect when, previous work in stream has completed. Any previous association is automatically replaced.
  • dptr must point to one of the following types of memories: managed memory declared using the managed keyword or allocated with muMemAllocManaged. a valid host-accessible region of system-allocated pageable memory. This type of memory may only be specified if the device associated with the stream reports a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_PAGEABLE_MEMORY_ACCESS.
  • For managed allocations, length must be either zero or the entire allocation's size. Both indicate that the entire allocation's stream association is being changed. Currently, it is not possible to change stream association for a portion of a managed allocation.
  • For pageable host allocations, length must be non-zero.
  • The stream association is specified using flags which must be one of MUmemAttach_flags. If the MU_MEM_ATTACH_GLOBAL flag is specified, the memory can be accessed by any stream on any device. If the MU_MEM_ATTACH_HOST flag is specified, the program makes a guarantee that it won't access the memory on the device from any stream on a device that has a zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. If the MU_MEM_ATTACH_SINGLE flag is specified and hStream is associated with a device that has a zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS, the program makes a guarantee that it will only access the memory on the device from hStream. It is illegal to attach singly to the NULL stream, because the NULL stream is a virtual global stream and not a specific stream. An error will be returned in this case.
  • When memory is associated with a single stream, the Unified Memory system will allow CPU access to this memory region so long as all operations in hStream have completed, regardless of whether other streams are active. In effect, this constrains exclusive ownership of the managed memory region by an active GPU to per-stream activity instead of whole-GPU activity.
  • Accessing memory on the device from streams that are not associated with it will produce undefined results. No error checking is performed by the Unified Memory system to ensure that kernels launched into other streams do not access this region.
  • It is a program's responsibility to order calls to muStreamAttachMemAsync via events, synchronization or other means to ensure legal access to memory at all times. Data visibility and coherency will be changed appropriately for all kernels which follow a stream-association change.
  • If hStream is destroyed while data is associated with it, the association is removed and the association reverts to the default visibility of the allocation as specified at muMemAllocManaged. For managed variables, the default association is always MU_MEM_ATTACH_GLOBAL. Note that destroying a stream is an asynchronous operation, and as a result, the change to default association won't happen until all work in the stream has completed.

Parameters

  • hStream (MUstream): Stream in which to enqueue the attach operation
  • dptr (MUdeviceptr): Pointer to memory (must be a pointer to managed memory or to a valid host-accessible region of system-allocated pageable memory)
  • length (size_t): Length of memory
  • flags (unsigned int): Must be one of MUmemAttach_flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamAttachMemAsync_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muStreamQuery​

MUresult muStreamQuery(MUstream hStream)

Description

  • Determine status of a compute stream.
  • Returns MUSA_SUCCESS if all operations in the stream specified by hStream have completed, or MUSA_ERROR_NOT_READY if not.
  • For the purposes of Unified Memory, a return value of MUSA_SUCCESS is equivalent to having called muStreamSynchronize().

Parameters

  • hStream (MUstream): Stream to query status of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_READY

Note

  • Additional exported symbol names in scope: muStreamQuery_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muStreamSynchronize​

MUresult muStreamSynchronize(MUstream hStream)

Description

  • Wait until a stream's tasks are completed.
  • Waits until the device has completed all operations in the stream specified by hStream. If the context was created with the MU_CTX_SCHED_BLOCKING_SYNC flag, the CPU thread will block until the stream is finished with all of its tasks.

Parameters

  • hStream (MUstream): Stream to wait for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muStreamSynchronize_ptsz.

See also

muStreamDestroy​

MUresult muStreamDestroy(MUstream hStream)

Description

  • Destroys a stream.
  • Destroys the stream specified by hStream.
  • In case the device is still doing work in the stream hStream when muStreamDestroy() is called, the function will return immediately and the resources associated with hStream will be released automatically once the device has completed all work in hStream.

Parameters

  • hStream (MUstream): Stream to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muStreamDestroy_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamCopyAttributes​

MUresult muStreamCopyAttributes(MUstream dst, MUstream src)

Description

  • Copies attributes from source stream to destination stream.
  • Copies attributes from source stream src to destination stream dst. Both streams must have the same context.

Parameters

  • dst (MUstream): Destination stream
  • src (MUstream): Source stream For list of attributes see MUstreamAttrID

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muStreamGetAttribute​

MUresult muStreamGetAttribute(MUstream hStream, MUstreamAttrID attr, MUstreamAttrValue *value_out)

Description

  • Queries stream attribute.
  • Queries attribute attr from hStream and stores it in corresponding member of value_out.

Parameters

  • hStream (MUstream)
  • attr (MUstreamAttrID)
  • value_out (MUstreamAttrValue *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muStreamSetAttribute​

MUresult muStreamSetAttribute(MUstream hStream, MUstreamAttrID attr, const MUstreamAttrValue *value)

Description

  • Sets stream attribute.
  • Sets attribute attr on hStream from corresponding attribute of value. The updated attribute will be applied to subsequent work submitted to the stream. It will not affect previously submitted work.

Parameters

  • hStream (MUstream)
  • attr (MUstreamAttrID)
  • value (const MUstreamAttrValue *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

3.17 Event Management​

muEventCreate​

MUresult muEventCreate(MUevent *phEvent, unsigned int Flags)

Description

  • Creates an event.
  • Creates an event *phEvent for the current context with the flags specified via Flags. Valid flags include: MU_EVENT_DEFAULT: Default event creation flag. MU_EVENT_BLOCKING_SYNC: Specifies that the created event should use blocking synchronization. A CPU thread that uses muEventSynchronize() to wait on an event created with this flag will block until the event has actually been recorded. MU_EVENT_DISABLE_TIMING: Specifies that the created event does not need to record timing data. Events created with this flag specified and the MU_EVENT_BLOCKING_SYNC flag not specified will provide the best performance when used with muStreamWaitEvent() and muEventQuery(). MU_EVENT_INTERPROCESS: Specifies that the created event may be used as an interprocess event by muIpcGetEventHandle(). MU_EVENT_INTERPROCESS must be specified along with MU_EVENT_DISABLE_TIMING.

Parameters

  • phEvent (MUevent *): Returns newly created event
  • Flags (unsigned int): Event creation flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muEventRecord​

MUresult muEventRecord(MUevent hEvent, MUstream hStream)

Description

  • Records an event.
  • Captures in hEvent the contents of hStream at the time of this call. hEvent and hStream must be from the same context otherwise MUSA_ERROR_INVALID_HANDLE is returned. Calls such as muEventQuery() or muStreamWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hStream after this call do not modify hEvent. See note on default stream behavior for what is captured in the default case.
  • muEventRecord() can be called multiple times on the same event and will overwrite the previously captured state. Other APIs such as muStreamWaitEvent() use the most recently captured state at the time of the API call, and are not affected by later calls to muEventRecord(). Before the first call to muEventRecord(), an event represents an empty set of work, so for example muEventQuery() would return MUSA_SUCCESS.

Parameters

  • hEvent (MUevent): Event to record
  • hStream (MUstream): Stream to record event for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muEventRecord_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muEventRecordWithFlags​

MUresult muEventRecordWithFlags(MUevent hEvent, MUstream hStream, unsigned int flags)

Description

  • Records an event.
  • Captures in hEvent the contents of hStream at the time of this call. hEvent and hStream must be from the same context otherwise MUSA_ERROR_INVALID_HANDLE is returned. Calls such as muEventQuery() or muStreamWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hStream after this call do not modify hEvent. See note on default stream behavior for what is captured in the default case.
  • muEventRecordWithFlags() can be called multiple times on the same event and will overwrite the previously captured state. Other APIs such as muStreamWaitEvent() use the most recently captured state at the time of the API call, and are not affected by later calls to muEventRecordWithFlags(). Before the first call to muEventRecordWithFlags(), an event represents an empty set of work, so for example muEventQuery() would return MUSA_SUCCESS.
  • flags include: MU_EVENT_RECORD_DEFAULT: Default event creation flag. MU_EVENT_RECORD_EXTERNAL: Event is captured in the graph as an external event node when performing stream capture. This flag is invalid outside of stream capture.

Parameters

  • hEvent (MUevent): Event to record
  • hStream (MUstream): Stream to record event for
  • flags (unsigned int): See MUevent_capture_flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muEventRecordWithFlags_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muEventQuery​

MUresult muEventQuery(MUevent hEvent)

Description

  • Queries an event's status.
  • Queries the status of all work currently captured by hEvent. See muEventRecord() for details on what is captured by an event.
  • Returns MUSA_SUCCESS if all captured work has been completed, or MUSA_ERROR_NOT_READY if any captured work is incomplete.
  • For the purposes of Unified Memory, a return value of MUSA_SUCCESS is equivalent to having called muEventSynchronize().

Parameters

  • hEvent (MUevent): Event to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_READY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muEventSynchronize​

MUresult muEventSynchronize(MUevent hEvent)

Description

  • Waits for an event to complete.
  • Waits until the completion of all work currently captured in hEvent. See muEventRecord() for details on what is captured by an event.
  • Waiting for an event that was created with the MU_EVENT_BLOCKING_SYNC flag will cause the calling CPU thread to block until the event has been completed by the device. If the MU_EVENT_BLOCKING_SYNC flag has not been set, then the CPU thread will busy-wait until the event has been completed by the device.

Parameters

  • hEvent (MUevent): Event to wait for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muEventDestroy​

MUresult muEventDestroy(MUevent hEvent)

Description

  • Destroys an event.
  • Destroys the event specified by hEvent.
  • An event may be destroyed before it is complete (i.e., while muEventQuery() would return MUSA_ERROR_NOT_READY). In this case, the call does not block on completion of the event, and any associated resources will automatically be released asynchronously at completion.

Parameters

  • hEvent (MUevent): Event to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • Additional exported symbol names in scope: muEventDestroy_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muEventElapsedTime​

MUresult muEventElapsedTime(float *pMilliseconds, MUevent hStart, MUevent hEnd)

Description

  • Computes the elapsed time between two events.
  • Computes the elapsed time between two events (in milliseconds with a resolution of around 0.5 microseconds).
  • If either event was last recorded in a non-NULL stream, the resulting time may be greater than expected (even if both used the same stream handle). This happens because the muEventRecord() operation takes place asynchronously and there is no guarantee that the measured latency is actually just between the two events. Any number of other different stream operations could execute in between the two measured events, thus altering the timing in a significant way.
  • If muEventRecord() has not been called on either event then MUSA_ERROR_INVALID_HANDLE is returned. If muEventRecord() has been called on both events but one or both of them has not yet been completed (that is, muEventQuery() would return MUSA_ERROR_NOT_READY on at least one of the events), MUSA_ERROR_NOT_READY is returned. If either event was created with the MU_EVENT_DISABLE_TIMING flag, then this function will return MUSA_ERROR_INVALID_HANDLE.
  • Note there is a later version of this API, muEventElapsedTime_v2. It will supplant this version in MUSA 13.0, which is retained for minor version compatibility.

Parameters

  • pMilliseconds (float *): Time between hStart and hEnd in ms
  • hStart (MUevent): Starting event
  • hEnd (MUevent): Ending event

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_READY, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muEventElapsedTime_v2​

MUresult muEventElapsedTime_v2(float *pMilliseconds, MUevent hStart, MUevent hEnd)

Description

  • Computes the elapsed time between two events.
  • Computes the elapsed time between two events (in milliseconds with a resolution of around 0.5 microseconds). Note this API is not guaranteed to return the latest errors for pending work. As such this API is intended to serve as an elapsed time calculation only and any polling for completion on the events to be compared should be done with muEventQuery instead.
  • If either event was last recorded in a non-NULL stream, the resulting time may be greater than expected (even if both used the same stream handle). This happens because the muEventRecord() operation takes place asynchronously and there is no guarantee that the measured latency is actually just between the two events. Any number of other different stream operations could execute in between the two measured events, thus altering the timing in a significant way.
  • If muEventRecord() has not been called on either event then MUSA_ERROR_INVALID_HANDLE is returned. If muEventRecord() has been called on both events but one or both of them has not yet been completed (that is, muEventQuery() would return MUSA_ERROR_NOT_READY on at least one of the events), MUSA_ERROR_NOT_READY is returned. If either event was created with the MU_EVENT_DISABLE_TIMING flag, then this function will return MUSA_ERROR_INVALID_HANDLE.

Parameters

  • pMilliseconds (float *): Time between hStart and hEnd in ms
  • hStart (MUevent): Starting event
  • hEnd (MUevent): Ending event

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_READY, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.18 External Resource Interoperability​

muImportExternalMemory​

MUresult muImportExternalMemory(MUexternalMemory *extMem_out, const MUSA_EXTERNAL_MEMORY_HANDLE_DESC *memHandleDesc)

Description

  • Imports an external memory object.
  • Imports an externally allocated memory object and returns a handle to that in extMem_out.
  • The properties of the handle being imported must be described in memHandleDesc. The MUSA_EXTERNAL_MEMORY_HANDLE_DESC structure is defined as follows:
typedef struct MUSA_EXTERNAL_MEMORY_HANDLE_DESC_st {
  MUexternalMemoryHandleTypetype;
  union {
    int fd;
    struct {
      void *handle;
      const void *name;
    } win32;
    const void *mtSciBufObject;
  } handle;
  unsigned long long size;
  unsigned int flags;
} MUSA_EXTERNAL_MEMORY_HANDLE_DESC;
  • where MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type specifies the type of handle being imported. MUexternalMemoryHandleType is defined as:
typedef enum MUexternalMemoryHandleType_enum {
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD = 1,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32 = 2,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT = 3,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP = 4,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE = 5,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE = 6,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE_KMT = 7,
  MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF = 8,
} MUexternalMemoryHandleType;
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::fd must be a valid file descriptor referencing a memory object. Ownership of the file descriptor is transferred to the MUSA driver when the handle is imported successfully. Performing any operations on the file descriptor after it is imported results in undefined behavior.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32, then exactly one of MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that references a memory object. Ownership of this handle is not transferred to MUSA after the import operation, so the application must release the handle using the appropriate system call. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name is not NULL, then it must point to a NULL-terminated array of UTF-16 characters that refers to a memory object.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle must be non-NULL and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must be NULL. The handle specified must be a globally shared KMT handle. This handle does not hold a reference to the underlying object, and thus will be invalid when all references to the memory object are destroyed.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP, then exactly one of MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that is returned by ID3D12Device::CreateSharedHandle when referring to a ID3D12Heap object. This handle holds a reference to the underlying object. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name is not NULL, then it must point to a NULL-terminated array of UTF-16 characters that refers to a ID3D12Heap object.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE, then exactly one of MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that is returned by ID3D12Device::CreateSharedHandle when referring to a ID3D12Resource object. This handle holds a reference to the underlying object. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name is not NULL, then it must point to a NULL-terminated array of UTF-16 characters that refers to a ID3D12Resource object.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle must represent a valid shared NT handle that is returned by IDXGIResource1::CreateSharedHandle when referring to a ID3D11Resource object. If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name is not NULL, then it must point to a NULL-terminated array of UTF-16 characters that refers to a ID3D11Resource object.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE_KMT, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::handle must represent a valid shared KMT handle that is returned by IDXGIResource::GetSharedHandle when referring to a ID3D11Resource object and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::win32::name must be NULL.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::mtSciBufObject must be non-NULL and reference a valid NvSciBuf object. If the NvSciBuf object imported into MUSA is also mapped by other drivers, then the application must use muWaitExternalSemaphoresAsync or muSignalExternalSemaphoresAsync as appropriate barriers to maintain coherence between MUSA and the other drivers. See MUSA_EXTERNAL_SEMAPHORE_SIGNAL_SKIP_MTSCIBUF_MEMSYNC and MUSA_EXTERNAL_SEMAPHORE_WAIT_SKIP_MTSCIBUF_MEMSYNC for memory synchronization.
  • If MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_DMABUF_FD, then MUSA_EXTERNAL_MEMORY_HANDLE_DESC::handle::fd must be a valid file descriptor referencing a dma_buf object and MUSA_EXTERNAL_MEMORY_HANDLE_DESC::flags must be zero. Importing a dma_buf object is supported only on Tegra Jetson platform starting with Thor series. Mapping an imported dma_buf object as MUSA mipmapped array using muExternalMemoryGetMappedMipmappedArray is not supported.
  • The size of the memory object must be specified in MUSA_EXTERNAL_MEMORY_HANDLE_DESC::size.
  • Specifying the flag MUSA_EXTERNAL_MEMORY_DEDICATED in MUSA_EXTERNAL_MEMORY_HANDLE_DESC::flags indicates that the resource is a dedicated resource. The definition of what a dedicated resource is outside the scope of this extension. This flag must be set if MUSA_EXTERNAL_MEMORY_HANDLE_DESC::type is one of the following: MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE MU_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_RESOURCE_KMT

Parameters

  • extMem_out (MUexternalMemory *): Returned handle to an external memory object
  • memHandleDesc (const MUSA_EXTERNAL_MEMORY_HANDLE_DESC *): Memory import handle descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OPERATING_SYSTEM

Note

  • This function may also return error codes from previous, asynchronous launches.
  • If the Vulkan memory imported into MUSA is mapped on the CPU then the application must use vkInvalidateMappedMemoryRanges/vkFlushMappedMemoryRanges as well as appropriate Vulkan pipeline barriers to maintain coherence between CPU and GPU. For more information on these APIs, please refer to "Synchronization and Cache Control" chapter from Vulkan specification.

See also

muExternalMemoryGetMappedBuffer​

MUresult muExternalMemoryGetMappedBuffer(MUdeviceptr *devPtr, MUexternalMemory extMem, const MUSA_EXTERNAL_MEMORY_BUFFER_DESC *bufferDesc)

Description

  • Maps a buffer onto an imported memory object.
  • Maps a buffer onto an imported memory object and returns a device pointer in devPtr.
  • The properties of the buffer being mapped must be described in bufferDesc. The MUSA_EXTERNAL_MEMORY_BUFFER_DESC structure is defined as follows:
typedef struct MUSA_EXTERNAL_MEMORY_BUFFER_DESC_st {
  unsigned long long offset;
  unsigned long long size;
  unsigned int flags;
} MUSA_EXTERNAL_MEMORY_BUFFER_DESC;
  • where MUSA_EXTERNAL_MEMORY_BUFFER_DESC::offset is the offset in the memory object where the buffer's base address is. MUSA_EXTERNAL_MEMORY_BUFFER_DESC::size is the size of the buffer. MUSA_EXTERNAL_MEMORY_BUFFER_DESC::flags must be zero.
  • The offset and size have to be suitably aligned to match the requirements of the external API. Mapping two buffers whose ranges overlap may or may not result in the same virtual address being returned for the overlapped portion. In such cases, the application must ensure that all accesses to that region from the GPU are volatile. Otherwise writes made via one address are not guaranteed to be visible via the other address, even if they're issued by the same thread. It is recommended that applications map the combined range instead of mapping separate buffers and then apply the appropriate offsets to the returned pointer to derive the individual buffers.
  • The returned pointer devPtr must be freed using muMemFree.

Parameters

  • devPtr (MUdeviceptr *): Returned device pointer to buffer
  • extMem (MUexternalMemory): Handle to external memory object
  • bufferDesc (const MUSA_EXTERNAL_MEMORY_BUFFER_DESC *): Buffer descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muExternalMemoryGetMappedMipmappedArray​

MUresult muExternalMemoryGetMappedMipmappedArray(MUmipmappedArray *mipmap, MUexternalMemory extMem, const MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC *mipmapDesc)

Description

  • Maps a MUSA mipmapped array onto an external memory object.
  • Maps a MUSA mipmapped array onto an external object and returns a handle to it in mipmap.
  • The properties of the MUSA mipmapped array being mapped must be described in mipmapDesc. The structure MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC is defined as follows:
typedef struct MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC_st {
  unsigned long long offset;
  MUSA_ARRAY3D_DESCRIPTORarrayDesc;
  unsigned int numLevels;
} MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC;
  • where MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::offset is the offset in the memory object where the base level of the mipmap chain is. MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::arrayDesc describes the format, dimensions and type of the base level of the mipmap chain. For further details on these parameters, please refer to the documentation for muMipmappedArrayCreate. Note that if the mipmapped array is bound as a color target in the graphics API, then the flag MUSA_ARRAY3D_COLOR_ATTACHMENT must be specified in MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::arrayDesc::Flags. MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::numLevels specifies the total number of levels in the mipmap chain.
  • If extMem was imported from a handle of type MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF, then MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC::numLevels must be equal to 1.
  • Mapping extMem imported from a handle of type MU_EXTERNAL_MEMORY_HANDLE_TYPE_DMABUF_FD, is not supported.
  • The returned MUSA mipmapped array must be freed using muMipmappedArrayDestroy.

Parameters

  • mipmap (MUmipmappedArray *): Returned MUSA mipmapped array
  • extMem (MUexternalMemory): Handle to external memory object
  • mipmapDesc (const MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC *): MUSA array descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDestroyExternalMemory​

MUresult muDestroyExternalMemory(MUexternalMemory extMem)

Description

  • Destroys an external memory object.
  • Destroys the specified external memory object. Any existing buffers and MUSA mipmapped arrays mapped onto this object must no longer be used and must be explicitly freed using muMemFree and muMipmappedArrayDestroy respectively.

Parameters

  • extMem (MUexternalMemory): External memory object to be destroyed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muImportExternalSemaphore​

MUresult muImportExternalSemaphore(MUexternalSemaphore *extSem_out, const MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC *semHandleDesc)

Description

  • Imports an external semaphore.
  • Imports an externally allocated synchronization object and returns a handle to that in extSem_out.
  • The properties of the handle being imported must be described in semHandleDesc. The MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC is defined as follows:
typedef struct MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC_st {
  MUexternalSemaphoreHandleTypetype;
  union {
    int fd;
    struct {
      void *handle;
      const void *name;
    } win32;
    const void *NvSciSyncObj;
  } handle;
  unsigned int flags;
} MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC;
  • where MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type specifies the type of handle being imported. MUexternalSemaphoreHandleType is defined as:
typedef enum MUexternalSemaphoreHandleType_enum {
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD = 1,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32 = 2,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT = 3,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE = 4,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE = 5,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC = 6,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX = 7,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX_KMT = 8,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_FD = 9,
  MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_WIN32 = 10;
} MUexternalSemaphoreHandleType;
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::fd must be a valid file descriptor referencing a synchronization object. Ownership of the file descriptor is transferred to the MUSA driver when the handle is imported successfully. Performing any operations on the file descriptor after it is imported results in undefined behavior.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32, then exactly one of MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that references a synchronization object. Ownership of this handle is not transferred to MUSA after the import operation, so the application must release the handle using the appropriate system call. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a valid synchronization object.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle must be non-NULL and MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must be NULL. The handle specified must be a globally shared KMT handle. This handle does not hold a reference to the underlying object, and thus will be invalid when all references to the synchronization object are destroyed.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, then exactly one of MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that is returned by ID3D12Device::CreateSharedHandle when referring to a ID3D12Fence object. This handle holds a reference to the underlying object. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a valid synchronization object that refers to a valid ID3D12Fence object.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle represents a valid shared NT handle that is returned by ID3D11Fence::CreateSharedHandle. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a valid synchronization object that refers to a valid ID3D11Fence object.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::mtSciSyncObj represents a valid NvSciSyncObj.
  • MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle represents a valid shared NT handle that is returned by IDXGIResource1::CreateSharedHandle when referring to a IDXGIKeyedMutex object. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a valid synchronization object that refers to a valid IDXGIKeyedMutex object.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX_KMT, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle represents a valid shared KMT handle that is returned by IDXGIResource::GetSharedHandle when referring to a IDXGIKeyedMutex object and MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must be NULL.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_FD, then MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::fd must be a valid file descriptor referencing a synchronization object. Ownership of the file descriptor is transferred to the MUSA driver when the handle is imported successfully. Performing any operations on the file descriptor after it is imported results in undefined behavior.
  • If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::type is MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_WIN32, then exactly one of MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle and MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name must not be NULL. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::handle is not NULL, then it must represent a valid shared NT handle that references a synchronization object. Ownership of this handle is not transferred to MUSA after the import operation, so the application must release the handle using the appropriate system call. If MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC::handle::win32::name is not NULL, then it must name a valid synchronization object.

Parameters

  • extSem_out (MUexternalSemaphore *): Returned handle to an external semaphore
  • semHandleDesc (const MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC *): Semaphore import handle descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OPERATING_SYSTEM

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muSignalExternalSemaphoresAsync​

MUresult muSignalExternalSemaphoresAsync(const MUexternalSemaphore *extSemArray, const MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS *paramsArray, unsigned int numExtSems, MUstream stream)

Description

  • Signals a set of external semaphore objects.
  • Enqueues a signal operation on a set of externally allocated semaphore object in the specified stream. The operations will be executed when all prior operations in the stream complete.
  • The exact semantics of signaling a semaphore depends on the type of the object.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT then signaling the semaphore will set it to the signaled state.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_FD, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_WIN32 then the semaphore will be set to the value specified in MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS::params::fence::value.
  • If the semaphore object is of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC this API sets MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS::params::mtSciSync::fence to a value that can be used by subsequent waiters of the same NvSciSync object to order operations with those currently submitted in stream. Such an update will overwrite previous contents of MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS::params::mtSciSync::fence. By default, signaling such an external semaphore object causes appropriate memory synchronization operations to be performed over all external memory objects that are imported as MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF. This ensures that any subsequent accesses made by other importers of the same set of NvSciBuf memory object(s) are coherent. These operations can be skipped by specifying the flag MUSA_EXTERNAL_SEMAPHORE_SIGNAL_SKIP_MTSCIBUF_MEMSYNC, which can be used as a performance optimization when data coherency is not required. But specifying this flag in scenarios where data coherency is required results in undefined behavior. Also, for semaphore object of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC, if the NvSciSyncAttrList used to create the NvSciSyncObj had not set the flags in muDeviceGetMtSciSyncAttributes to MUSA_MTSCISYNC_ATTR_SIGNAL, this API will return MUSA_ERROR_NOT_SUPPORTED. NvSciSyncFence associated with semaphore object of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC can be deterministic. For this the NvSciSyncAttrList used to create the semaphore object must have value of NvSciSyncAttrKey_RequireDeterministicFences key set to true. Deterministic fences allow users to enqueue a wait over the semaphore object even before corresponding signal is enqueued. For such a semaphore object, MUSA guarantees that each signal operation will increment the fence value by '1'. Users are expected to track count of signals enqueued on the semaphore object and insert waits accordingly. When such a semaphore object is signaled from multiple streams, due to concurrent stream execution, it is possible that the order in which the semaphore gets signaled is indeterministic. This could lead to waiters of the semaphore getting unblocked incorrectly. Users are expected to handle such situations, either by not using the same semaphore object with deterministic fence support enabled in different streams or by adding explicit dependency amongst such streams so that the semaphore is signaled in order. NvSciSyncFence associated with semaphore object of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_NVSCISYNC can be timestamp enabled. For this the NvSciSyncAttrList used to create the object must have the value of NvSciSyncAttrKey_WaiterRequireTimestamps key set to true. Timestamps are emitted asynchronously by the GPU and MUSA saves the GPU timestamp in the corresponding NvSciSyncFence at the time of signal on GPU. Users are expected to convert GPU clocks to CPU clocks using appropriate scaling functions. Users are expected to wait for the completion of the fence before extracting timestamp using appropriate NvSciSync APIs. Users are expected to ensure that there is only one outstanding timestamp enabled fence per Musa-MtSciSync object at any point of time, failing which leads to undefined behavior. Extracting the timestamp before the corresponding fence is signalled could lead to undefined behaviour. Timestamp extracted via appropriate NvSciSync API would be in microseconds.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX_KMT then the keyed mutex will be released with the key specified in MUSA_EXTERNAL_SEMAPHORE_PARAMS::params::keyedmutex::key.

Parameters

  • extSemArray (const MUexternalSemaphore *): Set of external semaphores to be signaled
  • paramsArray (const MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS *): Array of semaphore parameters
  • numExtSems (unsigned int): Number of semaphores to signal
  • stream (MUstream): Stream to enqueue the signal operations in

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muWaitExternalSemaphoresAsync​

MUresult muWaitExternalSemaphoresAsync(const MUexternalSemaphore *extSemArray, const MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS *paramsArray, unsigned int numExtSems, MUstream stream)

Description

  • Waits on a set of external semaphore objects.
  • Enqueues a wait operation on a set of externally allocated semaphore object in the specified stream. The operations will be executed when all prior operations in the stream complete.
  • The exact semantics of waiting on a semaphore depends on the type of the object.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT then waiting on the semaphore will wait until the semaphore reaches the signaled state. The semaphore will then be reset to the unsignaled state. Therefore for every signal operation, there can only be one wait operation.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D12_FENCE, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_FENCE, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_FD, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_TIMELINE_SEMAPHORE_WIN32 then waiting on the semaphore will wait until the value of the semaphore is greater than or equal to MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS::params::fence::value.
  • If the semaphore object is of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC then, waiting on the semaphore will wait until the MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS::params::mtSciSync::fence is signaled by the signaler of the NvSciSyncObj that was associated with this semaphore object. By default, waiting on such an external semaphore object causes appropriate memory synchronization operations to be performed over all external memory objects that are imported as MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF. This ensures that any subsequent accesses made by other importers of the same set of NvSciBuf memory object(s) are coherent. These operations can be skipped by specifying the flag MUSA_EXTERNAL_SEMAPHORE_WAIT_SKIP_MTSCIBUF_MEMSYNC, which can be used as a performance optimization when data coherency is not required. But specifying this flag in scenarios where data coherency is required results in undefined behavior. Also, for semaphore object of the type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC, if the NvSciSyncAttrList used to create the NvSciSyncObj had not set the flags in muDeviceGetMtSciSyncAttributes to MUSA_MTSCISYNC_ATTR_WAIT, this API will return MUSA_ERROR_NOT_SUPPORTED.
  • If the semaphore object is any one of the following types: MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX, MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_D3D11_KEYED_MUTEX_KMT then the keyed mutex will be acquired when it is released with the key specified in MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS::params::keyedmutex::key or until the timeout specified by MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS::params::keyedmutex::timeoutMs has lapsed. The timeout interval can either be a finite value specified in milliseconds or an infinite value. In case an infinite value is specified the timeout never elapses. The windows INFINITE macro must be used to specify infinite timeout.

Parameters

  • extSemArray (const MUexternalSemaphore *): External semaphores to be waited on
  • paramsArray (const MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS *): Array of semaphore parameters
  • numExtSems (unsigned int): Number of semaphores to wait on
  • stream (MUstream): Stream to enqueue the wait operations in

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_TIMEOUT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDestroyExternalSemaphore​

MUresult muDestroyExternalSemaphore(MUexternalSemaphore extSem)

Description

  • Destroys an external semaphore.
  • Destroys an external semaphore object and releases any references to the underlying resource. Any outstanding signals or waits must have completed before the semaphore is destroyed.

Parameters

  • extSem (MUexternalSemaphore): External semaphore to be destroyed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.19 Stream Memory Operations​

muStreamWaitValue32​

MUresult muStreamWaitValue32(MUstream stream, MUdeviceptr addr, muuint32_t value, unsigned int flags)

Description

  • Wait on a memory location.
  • Enqueues a synchronization of the stream on the given memory location. Work ordered after the operation will block until the given condition on the memory is satisfied. By default, the condition is to wait for (int32_t)(*addr - value) >= 0, a cyclic greater-or-equal. Other condition types can be specified via flags.
  • If the memory was registered via muMemHostRegister(), the device pointer should be obtained with muMemHostGetDevicePointer(). This function cannot be used with managed memory (muMemAllocManaged).
  • Support for MU_STREAM_WAIT_VALUE_NOR can be queried with muDeviceGetAttribute() and MU_DEVICE_ATTRIBUTE_CAN_USE_STREAM_WAIT_VALUE_NOR_V2.

Parameters

  • stream (MUstream): The stream to synchronize on the memory location.
  • addr (MUdeviceptr): The memory location to wait on.
  • value (muuint32_t): The value to compare with the memory location.
  • flags (unsigned int): See MUstreamWaitValue_flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamWaitValue32_v2.
  • Warning: Improper use of this API may deadlock the application. Synchronization ordering established through this API is not visible to MUSA. MUSA tasks that are (even indirectly) ordered by this API should also have that order expressed with MUSA-visible dependencies such as events. This ensures that the scheduler does not serialize them in an improper order.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamWaitValue64​

MUresult muStreamWaitValue64(MUstream stream, MUdeviceptr addr, muuint64_t value, unsigned int flags)

Description

  • Wait on a memory location.
  • Enqueues a synchronization of the stream on the given memory location. Work ordered after the operation will block until the given condition on the memory is satisfied. By default, the condition is to wait for (int64_t)(*addr - value) >= 0, a cyclic greater-or-equal. Other condition types can be specified via flags.
  • If the memory was registered via muMemHostRegister(), the device pointer should be obtained with muMemHostGetDevicePointer().
  • Support for this can be queried with muDeviceGetAttribute() and MU_DEVICE_ATTRIBUTE_CAN_USE_64_BIT_STREAM_MEM_OPS.

Parameters

  • stream (MUstream): The stream to synchronize on the memory location.
  • addr (MUdeviceptr): The memory location to wait on.
  • value (muuint64_t): The value to compare with the memory location.
  • flags (unsigned int): See MUstreamWaitValue_flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamWaitValue64_v2.
  • Warning: Improper use of this API may deadlock the application. Synchronization ordering established through this API is not visible to MUSA. MUSA tasks that are (even indirectly) ordered by this API should also have that order expressed with MUSA-visible dependencies such as events. This ensures that the scheduler does not serialize them in an improper order.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamWriteValue32​

MUresult muStreamWriteValue32(MUstream stream, MUdeviceptr addr, muuint32_t value, unsigned int flags)

Description

  • Write a value to memory.
  • If the memory was registered via muMemHostRegister(), the device pointer should be obtained with muMemHostGetDevicePointer(). This function cannot be used with managed memory (muMemAllocManaged).

Parameters

  • stream (MUstream): The stream to do the write in.
  • addr (MUdeviceptr): The device address to write to.
  • value (muuint32_t): The value to write.
  • flags (unsigned int): See MUstreamWriteValue_flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamWriteValue32_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamWriteValue64​

MUresult muStreamWriteValue64(MUstream stream, MUdeviceptr addr, muuint64_t value, unsigned int flags)

Description

  • Write a value to memory.
  • If the memory was registered via muMemHostRegister(), the device pointer should be obtained with muMemHostGetDevicePointer().
  • Support for this can be queried with muDeviceGetAttribute() and MU_DEVICE_ATTRIBUTE_CAN_USE_64_BIT_STREAM_MEM_OPS.

Parameters

  • stream (MUstream): The stream to do the write in.
  • addr (MUdeviceptr): The device address to write to.
  • value (muuint64_t): The value to write.
  • flags (unsigned int): See MUstreamWriteValue_flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamWriteValue64_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muStreamBatchMemOp​

MUresult muStreamBatchMemOp(MUstream stream, unsigned int count, MUstreamBatchMemOpParams *paramArray, unsigned int flags)

Description

  • Batch operations to synchronize the stream via memory operations.
  • This is a batch version of muStreamWaitValue32() and muStreamWriteValue32(). Batching operations may avoid some performance overhead in both the API call and the device execution versus adding them to the stream in separate API calls. The operations are enqueued in the order they appear in the array.
  • See MUstreamBatchMemOpType for the full set of supported operations, and muStreamWaitValue32(), muStreamWaitValue64(), muStreamWriteValue32(), and muStreamWriteValue64() for details of specific operations.
  • See related APIs for details on querying support for specific operations.

Parameters

  • stream (MUstream): The stream to enqueue the operations in.
  • count (unsigned int): The number of operations in the array. Must be less than 256.
  • paramArray (MUstreamBatchMemOpParams *): The types and parameters of the individual operations.
  • flags (unsigned int): Reserved for future expansion; must be 0.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muStreamBatchMemOp_v2.
  • Warning: Improper use of this API may deadlock the application. Synchronization ordering established through this API is not visible to MUSA. MUSA tasks that are (even indirectly) ordered by this API should also have that order expressed with MUSA-visible dependencies such as events. This ensures that the scheduler does not serialize them in an improper order. For more information, see the Stream Memory Operations section in the programming guide(https://docs.mthreads.com/musa/musa-c-programming-guide/index.html).
  • This function may also return error codes from previous, asynchronous launches.

See also

3.20 Execution Control​

muFuncGetAttribute​

MUresult muFuncGetAttribute(int *pi, MUfunction_attribute attrib, MUfunction hfunc)

Description

  • Returns information about a function.
  • Returns in *pi the integer value of the attribute attrib on the kernel given by hfunc. The supported attributes are: MU_FUNC_ATTRIBUTE_MAX_THREADS_PER_BLOCK: The maximum number of threads per block, beyond which a launch of the function would fail. This number depends on both the function and the device on which the function is currently loaded. MU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES: The size in bytes of statically-allocated shared memory per block required by this function. This does not include dynamically-allocated shared memory requested by the user at runtime. MU_FUNC_ATTRIBUTE_CONST_SIZE_BYTES: The size in bytes of user-allocated constant memory required by this function. MU_FUNC_ATTRIBUTE_LOCAL_SIZE_BYTES: The size in bytes of local memory used by each thread of this function. MU_FUNC_ATTRIBUTE_NUM_REGS: The number of registers used by each thread of this function. MU_FUNC_ATTRIBUTE_PTX_VERSION: The PTX virtual architecture version for which the function was compiled. This value is the major PTX version * 10 the minor PTX version, so a PTX version 1.3 function would return the value 13. Note that this may return the undefined value of 0 for mubins compiled prior to MUSA 3.0. MU_FUNC_ATTRIBUTE_BINARY_VERSION: The binary architecture version for which the function was compiled. This value is the major binary version * 10 + the minor binary version, so a binary version 1.3 function would return the value 13. Note that this will return a value of 10 for legacy mubins that do not have a properly-encoded binary architecture version. MU_FUNC_CACHE_MODE_CA: The attribute to indicate whether the function has been compiled with user specified option "-Xptxas --dlcm=ca" set . MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: The maximum size in bytes of dynamically-allocated shared memory. MU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: Preferred shared memory-L1 cache split ratio in percent of total shared memory. MU_FUNC_ATTRIBUTE_CLUSTER_SIZE_MUST_BE_SET: If this attribute is set, the kernel must launch with a valid cluster size specified. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in blocks. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in blocks. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in blocks. MU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed. A non-portable cluster size may only function on the specific SKUs the program is tested on. The launch might fail if the program is run on a different hardware platform. MUSA API provides musaOccupancyMaxActiveClusters to assist with checking whether the desired size can be launched on the current device. A portable cluster size is guaranteed to be functional on all compute capabilities higher than the target compute capability. The portable cluster size for sm_90 is 8 blocks per cluster. This value may increase for future compute capabilities. The specific hardware unit may support higher cluster sizes that’s not guaranteed to be portable. MU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block scheduling policy of a function. The value type is MUclusterSchedulingPolicy.
  • With a few execeptions, function attributes may also be queried on unloaded function handles returned from muModuleEnumerateFunctions. MUSA_ERROR_FUNCTION_NOT_LOADED is returned if the attribute requires a fully loaded function but the function is not loaded. The loading state of a function may be queried using muFuncIsloaded. muFuncLoad may be called to explicitly load a function before querying the following attributes that require the function to be loaded: MU_FUNC_ATTRIBUTE_MAX_THREADS_PER_BLOCK MU_FUNC_ATTRIBUTE_CONST_SIZE_BYTES MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES

Parameters

  • pi (int *): Returned attribute value
  • attrib (MUfunction_attribute): Attribute requested
  • hfunc (MUfunction): Function to query attribute of

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_FUNCTION_NOT_LOADED

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muFuncSetAttribute​

MUresult muFuncSetAttribute(MUfunction hfunc, MUfunction_attribute attrib, int value)

Description

  • Sets information about a function.
  • This call sets the value of a specified attribute attrib on the kernel given by hfunc to an integer value specified by val This function returns MUSA_SUCCESS if the new value of the attribute could be successfully set. If the set fails, this call will return an error. Not all attributes can have values set. Attempting to set a value on a read-only attribute will result in an error (MUSA_ERROR_INVALID_VALUE)
  • Supported attributes for the muFuncSetAttribute call are: MU_FUNC_ATTRIBUTE_MAX_DYNAMIC_SHARED_SIZE_BYTES: This maximum size in bytes of dynamically-allocated shared memory. The value should contain the requested maximum size of dynamically-allocated shared memory. The sum of this value and the function attribute MU_FUNC_ATTRIBUTE_SHARED_SIZE_BYTES cannot exceed the device attribute MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_BLOCK_OPTIN. The maximal size of requestable dynamic shared memory may differ by GPU architecture. MU_FUNC_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT: On devices where the L1 cache and shared memory use the same hardware resources, this sets the shared memory carveout preference, in percent of the total shared memory. See MU_DEVICE_ATTRIBUTE_MAX_SHARED_MEMORY_PER_MULTIPROCESSOR This is only a hint, and the driver can choose a different ratio if required to execute the function. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_WIDTH: The required cluster width in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_HEIGHT: The required cluster height in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_REQUIRED_CLUSTER_DEPTH: The required cluster depth in blocks. The width, height, and depth values must either all be 0 or all be positive. The validity of the cluster dimensions is checked at launch time. If the value is set during compile time, it cannot be set at runtime. Setting it at runtime will return MUSA_ERROR_NOT_PERMITTED. MU_FUNC_ATTRIBUTE_NON_PORTABLE_CLUSTER_SIZE_ALLOWED: Indicates whether the function can be launched with non-portable cluster size. 1 is allowed, 0 is disallowed. MU_FUNC_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: The block scheduling policy of a function. The value type is MUclusterSchedulingPolicy.

Parameters

  • hfunc (MUfunction): Function to query attribute of
  • attrib (MUfunction_attribute): Attribute requested
  • value (int): The value to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muFuncSetCacheConfig​

MUresult muFuncSetCacheConfig(MUfunction hfunc, MUfunc_cache config)

Description

  • Sets the preferred cache configuration for a device function.
  • On devices where the L1 cache and shared memory use the same hardware resources, this sets through config the preferred cache configuration for the device function hfunc. This is only a preference. The driver will use the requested configuration if possible, but it is free to choose a different configuration if required to execute hfunc. Any context-wide preference set via muCtxSetCacheConfig() will be overridden by this per-function setting unless the per-function setting is MU_FUNC_CACHE_PREFER_NONE. In that case, the current context-wide setting will be used.
  • This setting does nothing on devices where the size of the L1 cache and shared memory are fixed.
  • Launching a kernel with a different preference than the most recent preference setting may insert a device-side synchronization point.
  • The supported cache configurations are: MU_FUNC_CACHE_PREFER_NONE: no preference for shared memory or L1 (default) MU_FUNC_CACHE_PREFER_SHARED: prefer larger shared memory and smaller L1 cache MU_FUNC_CACHE_PREFER_L1: prefer larger L1 cache and smaller shared memory MU_FUNC_CACHE_PREFER_EQUAL: prefer equal sized L1 cache and shared memory

Parameters

  • hfunc (MUfunction): Kernel to configure cache for
  • config (MUfunc_cache): Requested cache configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muFuncGetModule​

MUresult muFuncGetModule(MUmodule *hmod, MUfunction hfunc)

Description

  • Returns a module handle.
  • Returns in *hmod the handle of the module that function hfunc is located in. The lifetime of the module corresponds to the lifetime of the context it was loaded in or until the module is explicitly unloaded.
  • The MUSA runtime manages its own modules loaded into the primary context. If the handle returned by this API refers to a module loaded by the MUSA runtime, calling muModuleUnload() on that module will result in undefined behavior.

Parameters

  • hmod (MUmodule *): Returned module handle
  • hfunc (MUfunction): Function to retrieve module for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.

muFuncGetName​

MUresult muFuncGetName(const char **name, MUfunction hfunc)

Description

  • Returns the function name for a MUfunction handle.
  • Returns in **name the function name associated with the function handle hfunc . The function name is returned as a null-terminated string. The returned name is only valid when the function handle is valid. If the module is unloaded or reloaded, one must call the API again to get the updated name. This API may return a mangled name if the function is not declared as having C linkage. If either **name or hfunc is NULL, MUSA_ERROR_INVALID_VALUE is returned.

Parameters

  • name (const char **): The returned name of the function
  • hfunc (MUfunction): The function handle to retrieve the name for

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

muFuncGetParamInfo​

MUresult muFuncGetParamInfo(MUfunction func, size_t paramIndex, size_t *paramOffset, size_t *paramSize)

Description

  • Returns the offset and size of a kernel parameter in the device-side parameter layout.
  • Queries the kernel parameter at paramIndex into func's list of parameters, and returns in paramOffset and paramSize the offset and size, respectively, where the parameter will reside in the device-side parameter layout. This information can be used to update kernel node parameters from the device via musaGraphKernelNodeSetParam() and musaGraphKernelNodeUpdatesApply(). paramIndex must be less than the number of parameters that func takes. paramSize can be set to NULL if only the parameter offset is desired.

Parameters

  • func (MUfunction): The function to query
  • paramIndex (size_t): The parameter index to query
  • paramOffset (size_t *): Returns the offset into the device-side parameter layout at which the parameter resides
  • paramSize (size_t *): Optionally returns the size of the parameter in the device-side parameter layout

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muFuncGetParamCount​

MUresult muFuncGetParamCount(MUfunction hfunc, size_t *paramCount)

Description

  • Returns the number of parameters used by the function.
  • Queries the number of kernel parameters used by hfunc and returns it in paramCount.

Parameters

  • hfunc (MUfunction): The function handle to query
  • paramCount (size_t *): Returns the number of parameters used by the function

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • This function may also return error codes from previous, asynchronous launches.

muFuncIsLoaded​

MUresult muFuncIsLoaded(MUfunctionLoadingState *state, MUfunction function)

Description

  • Returns if the function is loaded.
  • Returns in state the loading state of function.

Parameters

  • state (MUfunctionLoadingState *): returned loading state
  • function (MUfunction): the function to check

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muFuncLoad​

MUresult muFuncLoad(MUfunction function)

Description

  • Loads a function.
  • Finalizes function loading for function. Calling this API with a fully loaded function has no effect.

Parameters

  • function (MUfunction): the function to load

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE

See also

muLaunchKernel​

MUresult muLaunchKernel(MUfunction f, unsigned int gridDimX, unsigned int gridDimY, unsigned int gridDimZ, unsigned int blockDimX, unsigned int blockDimY, unsigned int blockDimZ, unsigned int sharedMemBytes, MUstream hStream, void **kernelParams, void **extra)

Description

  • Launches a MUSA function MUfunction or a MUSA kernel MUkernel.
  • Invokes the function MUfunction or the kernel MUkernel f on a gridDimX x gridDimY x gridDimZ grid of blocks. Each block contains blockDimX x blockDimY x blockDimZ threads.
  • sharedMemBytes sets the amount of dynamic shared memory that will be available to each thread block.
  • Kernel parameters to f can be specified in one of two ways:
    1. Kernel parameters can be specified via kernelParams. If f has N parameters, then kernelParams needs to be an array of N pointers. Each of kernelParams[0] through kernelParams[N-1] must point to a region of memory from which the actual kernel parameter will be copied. The number of kernel parameters and their offsets and sizes do not need to be specified as that information is retrieved directly from the kernel's image.
    1. Kernel parameters can also be packaged by the application into a single buffer that is passed in via the extra parameter. This places the burden on the application of knowing each kernel parameter's size and alignment/padding within the buffer. Here is an example of using the extra parameter in this manner: size_targBufferSize; charargBuffer[256]; //populateargBufferandargBufferSize void*config[]={ MU_LAUNCH_PARAM_BUFFER_POINTER,argBuffer, MU_LAUNCH_PARAM_BUFFER_SIZE,&argBufferSize, MU_LAUNCH_PARAM_END }; status=muLaunchKernel(f,gx,gy,gz,bx,by,bz,sh,s,NULL,config);
  • The extra parameter exists to allow muLaunchKernel to take additional less commonly used arguments. extra specifies a list of names of extra settings and their corresponding values. Each extra setting name is immediately followed by the corresponding value. The list must be terminated with either NULL or MU_LAUNCH_PARAM_END.
  • MU_LAUNCH_PARAM_END, which indicates the end of the extra array; MU_LAUNCH_PARAM_BUFFER_POINTER, which specifies that the next value in extra will be a pointer to a buffer containing all the kernel parameters for launching kernel f; MU_LAUNCH_PARAM_BUFFER_SIZE, which specifies that the next value in extra will be a pointer to a size_t containing the size of the buffer specified with MU_LAUNCH_PARAM_BUFFER_POINTER;
  • The error MUSA_ERROR_INVALID_VALUE will be returned if kernel parameters are specified with both kernelParams and extra (i.e. both kernelParams and extra are non-NULL).
  • Calling muLaunchKernel() invalidates the persistent function state set through the following deprecated APIs: muFuncSetBlockShape(), muFuncSetSharedSize(), muParamSetSize(), muParamSeti(), muParamSetf(), muParamSetv().
  • Note that to use muLaunchKernel(), the kernel f must either have been compiled with toolchain version 3.2 or later so that it will contain kernel parameter information, or have no kernel parameters. If either of these conditions is not met, then muLaunchKernel() will return MUSA_ERROR_INVALID_IMAGE.
  • Note that the API can also be used to launch context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to launch the kernel on will either be taken from the specified stream hStream or the current context in case of NULL stream.

Parameters

  • f (MUfunction): Function MUfunction or Kernel MUkernel to launch
  • gridDimX (unsigned int): Width of grid in blocks
  • gridDimY (unsigned int): Height of grid in blocks
  • gridDimZ (unsigned int): Depth of grid in blocks
  • blockDimX (unsigned int): X dimension of each thread block
  • blockDimY (unsigned int): Y dimension of each thread block
  • blockDimZ (unsigned int): Z dimension of each thread block
  • sharedMemBytes (unsigned int): Dynamic shared-memory size per thread block in bytes
  • hStream (MUstream): Stream identifier
  • kernelParams (void **): Array of pointers to kernel parameters
  • extra (void **): Extra options

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_IMAGE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_NOT_FOUND

Note

  • Additional exported symbol names in scope: muLaunchKernel_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muLaunchKernelEx​

MUresult muLaunchKernelEx(const MUlaunchConfig *config, MUfunction f, void **kernelParams, void **extra)

Description

  • Launches a MUSA function MUfunction or a MUSA kernel MUkernel with launch-time configuration.
  • Invokes the function MUfunction or the kernel MUkernel f with the specified launch-time configuration config.
  • The MUlaunchConfig structure is defined as:
typedef struct MUlaunchConfig_st {
  unsigned int gridDimX;
  unsigned int gridDimY;
  unsigned int gridDimZ;
  unsigned int blockDimX;
  unsigned int blockDimY;
  unsigned int blockDimZ;
  unsigned int sharedMemBytes;
  MUstream hStream;
  MUlaunchAttribute *attrs;
  unsigned int numAttrs;
} MUlaunchConfig;
  • where: MUlaunchConfig::gridDimX is the width of the grid in blocks. MUlaunchConfig::gridDimY is the height of the grid in blocks. MUlaunchConfig::gridDimZ is the depth of the grid in blocks. MUlaunchConfig::blockDimX is the X dimension of each thread block. MUlaunchConfig::blockDimX is the Y dimension of each thread block. MUlaunchConfig::blockDimZ is the Z dimension of each thread block. MUlaunchConfig::sharedMemBytes is the dynamic shared-memory size per thread block in bytes. MUlaunchConfig::hStream is the handle to the stream to perform the launch in. The MUSA context associated with this stream must match that associated with function f. MUlaunchConfig::attrs is an array of MUlaunchConfig::numAttrs continguous MUlaunchAttribute elements. The value of this pointer is not considered if MUlaunchConfig::numAttrs is zero. However, in that case, it is recommended to set the pointer to NULL. MUlaunchConfig::numAttrs is the number of attributes populating the first MUlaunchConfig::numAttrs positions of the MUlaunchConfig::attrs array.
  • Launch-time configuration is specified by adding entries to MUlaunchConfig::attrs. Each entry is an attribute ID and a corresponding attribute value.
  • The MUlaunchAttribute structure is defined as:
typedef struct MUlaunchAttribute_st {
  MUlaunchAttribute ID id;
  MUlaunchAttribute Value value;
} MUlaunchAttribute;
  • where: MUlaunchAttribute::id is a unique enum identifying the attribute. MUlaunchAttribute::value is a union that hold the attribute value.
  • An example of using the config parameter: MUlaunchAttributecoopAttr={.id=MU_LAUNCH_ATTRIBUTE_COOPERATIVE, .value=1}; MUlaunchConfigconfig={...//setblockandgriddimensions .attrs=&coopAttr, .numAttrs=1}; muLaunchKernelEx(&config,kernel,NULL,NULL);
  • The MUlaunchAttributeID enum is defined as:
typedef enum MUlaunchAttribute ID_enum {
  MU_LAUNCH_ATTRIBUTE_IGNORE = 0,
  MU_LAUNCH_ATTRIBUTE_ACCESS_POLICY_WINDOW = 1,
  MU_LAUNCH_ATTRIBUTE_COOPERATIVE = 2,
  MU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY = 3,
  MU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION = 4,
  MU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE = 5,
  MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_STREAM_SERIALIZATION = 6,
  MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_EVENT = 7,
  MU_LAUNCH_ATTRIBUTE_PRIORITY = 8,
  MU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN_MAP = 9,
  MU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN = 10,
  MU_LAUNCH_ATTRIBUTE_PREFERRED_CLUSTER_DIMENSION = 11,
  MU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT = 12,
  MU_LAUNCH_ATTRIBUTE_DEVICE_UPDATABLE_KERNEL_NODE = 13,
} MUlaunchAttribute ID;
  • and the corresponding MUlaunchAttributeValue union as :
typedef union MUlaunchAttribute Value_union {
  MUaccessPolicyWindow accessPolicyWindow;
  int cooperative;
  MUsynchronizationPolicy syncPolicy;
  struct {
    unsigned int x;
    unsigned int y;
    unsigned int z;
  } clusterDim;
  MUclusterSchedulingPolicy clusterSchedulingPolicyPreference;
  int programmaticStreamSerializationAllowed;
  struct {
    MUevent event;
    int flags;
    int triggerAtBlockStart;
  } programmaticEvent;
  int priority;
  MUlaunchMemSyncDomainMapmemSyncDomainMap;
  MUlaunchMemSyncDomainmemSyncDomain;
  struct {
    unsigned int x;
    unsigned int y;
    unsigned int z;
  } preferredClusterDim;
  struct {
    MUevent event;
    int flags;
  } launchCompletionEvent;
  struct {
    int deviceUpdatable;
    MUgraphDeviceNode devNode;
  } deviceUpdatableKernelNode;
} MUlaunchAttribute Value;
  • Setting MU_LAUNCH_ATTRIBUTE_COOPERATIVE to a non-zero value causes the kernel launch to be a cooperative launch, with exactly the same usage and semantics of muLaunchCooperativeKernel.
  • Setting MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_STREAM_SERIALIZATION to a non-zero values causes the kernel to use programmatic means to resolve its stream dependency enabling the MUSA runtime to opportunistically allow the grid's execution to overlap with the previous kernel in the stream, if that kernel requests the overlap.
  • MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_EVENT records an event along with the kernel launch. Event recorded through this launch attribute is guaranteed to only trigger after all block in the associated kernel trigger the event. A block can trigger the event through PTX launchdep.release or MUSA builtin function musaTriggerProgrammaticLaunchCompletion(). A trigger can also be inserted at the beginning of each block's execution if triggerAtBlockStart is set to non-0. Note that dependents (including the CPU thread calling muEventSynchronize()) are not guaranteed to observe the release precisely when it is released. For example, muEventSynchronize() may only observe the event trigger long after the associated kernel has completed. This recording type is primarily meant for establishing programmatic dependency between device tasks. The event supplied must not be an interprocess or interop event. The event must disable timing (i.e. created with MU_EVENT_DISABLE_TIMING flag set).
  • MU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT records an event along with the kernel launch. Nominally, the event is triggered once all blocks of the kernel have begun execution. Currently this is a best effort. If a kernel B has a launch completion dependency on a kernel A, B may wait until A is complete. Alternatively, blocks of B may begin before all blocks of A have begun, for example:
  • If B can claim execution resources unavaiable to A, for example if they run on different GPUs. If B is a higher priority than A.
  • Exercise caution if such an ordering inversion could lead to deadlock. The event supplied must not be an interprocess or interop event. The event must disable timing (i.e. must be created with the MU_EVENT_DISABLE_TIMING flag set).
  • Setting MU_LAUNCH_ATTRIBUTE_DEVICE_UPDATABLE_KERNEL_NODE to 1 on a captured launch causes the resulting kernel node to be device-updatable. This attribute is specific to graphs, and passing it to a launch in a non-capturing stream results in an error. Passing a value other than 0 or 1 is not allowed.
  • On success, a handle will be returned via MUlaunchAttributeValue::deviceUpdatableKernelNode::devNode which can be passed to the various device-side update functions to update the node's kernel parameters from within another kernel. For more information on the types of device updates that can be made, as well as the relevant limitations thereof, see musaGraphKernelNodeUpdatesApply.
  • Kernel nodes which are device-updatable have additional restrictions compared to regular kernel nodes. Firstly, device-updatable nodes cannot be removed from their graph via muGraphDestroyNode. Additionally, once opted-in to this functionality, a node cannot opt out, and any attempt to set the attribute to 0 will result in an error. Graphs containing one or more device-updatable node also do not allow multiple instantiation.
  • MU_LAUNCH_ATTRIBUTE_PREFERRED_CLUSTER_DIMENSION allows the kernel launch to specify a preferred substitute cluster dimension. Blocks may be grouped according to either the dimensions specified with this attribute (grouped into a "preferred substitute cluster"), or the one specified with MU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION attribute (grouped into a "regular cluster"). The cluster dimensions of a "preferred substitute cluster" shall be an integer multiple greater than zero of the regular cluster dimensions. The device will attempt - on a best-effort basis - to group thread blocks into preferred clusters over grouping them into regular clusters. When it deems necessary (primarily when the device temporarily runs out of physical resources to launch the larger preferred clusters), the device may switch to launch the regular clusters instead to attempt to utilize as much of the physical device resources as possible.
  • Each type of cluster will have its enumeration / coordinate setup as if the grid consists solely of its type of cluster. For example, if the preferred substitute cluster dimensions double the regular cluster dimensions, there might be simultaneously a regular cluster indexed at (1,0,0), and a preferred cluster indexed at (1,0,0). In this example, the preferred substitute cluster (1,0,0) replaces regular clusters (2,0,0) and (3,0,0) and groups their blocks.
  • This attribute will only take effect when a regular cluster dimension has been specified. The preferred substitute The preferred substitute cluster dimension must be an integer multiple greater than zero of the regular cluster dimension and must divide the grid. It must also be no more than maxBlocksPerCluster, if it is set in the kernel's launch_bounds. Otherwise it must be less than the maximum value the driver can support. Otherwise, setting this attribute to a value physically unable to fit on any particular device is permitted.
  • The effect of other attributes is consistent with their effect when set via persistent APIs.
  • See muStreamSetAttribute for MU_LAUNCH_ATTRIBUTE_ACCESS_POLICY_WINDOW MU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY
  • See muFuncSetAttribute for MU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION MU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE
  • Kernel parameters to f can be specified in the same ways that they can be using muLaunchKernel.
  • Note that the API can also be used to launch context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to launch the kernel on will either be taken from the specified stream MUlaunchConfig::hStream or the current context in case of NULL stream.

Parameters

  • config (const MUlaunchConfig *): Config to launch
  • f (MUfunction): Function MUfunction or Kernel MUkernel to launch
  • kernelParams (void **): Array of pointers to kernel parameters
  • extra (void **): Extra options

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_IMAGE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_COOPERATIVE_LAUNCH_TOO_LARGE, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_NOT_FOUND

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muLaunchHostFunc​

MUresult muLaunchHostFunc(MUstream hStream, MUhostFn fn, void *userData)

Description

  • Launches a MUSA function MUfunction or a MUSA kernel MUkernel where thread blocks can cooperate and synchronize as they execute.
  • Invokes the function MUfunction or the kernel MUkernel f on a gridDimX x gridDimY x gridDimZ grid of blocks. Each block contains blockDimX x blockDimY x blockDimZ threads.
  • sharedMemBytes sets the amount of dynamic shared memory that will be available to each thread block.
  • The device on which this kernel is invoked must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_COOPERATIVE_LAUNCH.
  • The total number of blocks launched cannot exceed the maximum number of blocks per multiprocessor as returned by muOccupancyMaxActiveBlocksPerMultiprocessor (or muOccupancyMaxActiveBlocksPerMultiprocessorWithFlags) times the number of multiprocessors as specified by the device attribute MU_DEVICE_ATTRIBUTE_MULTIPROCESSOR_COUNT.
  • The kernel cannot make use of MUSA dynamic parallelism.
  • Kernel parameters must be specified via kernelParams. If f has N parameters, then kernelParams needs to be an array of N pointers. Each of kernelParams[0] through kernelParams[N-1] must point to a region of memory from which the actual kernel parameter will be copied. The number of kernel parameters and their offsets and sizes do not need to be specified as that information is retrieved directly from the kernel's image.
  • Calling muLaunchCooperativeKernel() sets persistent function state that is the same as function state set through muLaunchKernel API
  • When the kernel f is launched via muLaunchCooperativeKernel(), the previous block shape, shared size and parameter info associated with f is overwritten.
  • Note that to use muLaunchCooperativeKernel(), the kernel f must either have been compiled with toolchain version 3.2 or later so that it will contain kernel parameter information, or have no kernel parameters. If either of these conditions is not met, then muLaunchCooperativeKernel() will return MUSA_ERROR_INVALID_IMAGE.
  • Note that the API can also be used to launch context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to launch the kernel on will either be taken from the specified stream hStream or the current context in case of NULL stream.
  • DeprecatedThis function is deprecated as of MUSA 11.3.
  • Invokes kernels as specified in the launchParamsList array where each element of the array specifies all the parameters required to perform a single kernel launch. These kernels can cooperate and synchronize as they execute. The size of the array is specified by numDevices.
  • No two kernels can be launched on the same device. All the devices targeted by this multi-device launch must be identical. All devices must have a non-zero value for the device attribute MU_DEVICE_ATTRIBUTE_COOPERATIVE_MULTI_DEVICE_LAUNCH.
  • All kernels launched must be identical with respect to the compiled code. Note that any device, constant or managed variables present in the module that owns the kernel launched on each device, are independently instantiated on every device. It is the application's responsibility to ensure these variables are initialized and used appropriately.
  • The size of the grids as specified in blocks, the size of the blocks themselves and the amount of shared memory used by each thread block must also match across all launched kernels.
  • The streams used to launch these kernels must have been created via either muStreamCreate or muStreamCreateWithPriority. The NULL stream or MU_STREAM_LEGACY or MU_STREAM_PER_THREAD cannot be used.
  • The total number of blocks launched per kernel cannot exceed the maximum number of blocks per multiprocessor as returned by muOccupancyMaxActiveBlocksPerMultiprocessor (or muOccupancyMaxActiveBlocksPerMultiprocessorWithFlags) times the number of multiprocessors as specified by the device attribute MU_DEVICE_ATTRIBUTE_MULTIPROCESSOR_COUNT. Since the total number of blocks launched per device has to match across all devices, the maximum number of blocks that can be launched per device will be limited by the device with the least number of multiprocessors.
  • The kernels cannot make use of MUSA dynamic parallelism.
  • The MUSA_LAUNCH_PARAMS structure is defined as:
typedef struct MUSA_LAUNCH_PARAMS_st  {
  MUfunction function;
  unsigned int gridDimX;
  unsigned int gridDimY;
  unsigned int gridDimZ;
  unsigned int blockDimX;
  unsigned int blockDimY;
  unsigned int blockDimZ;
  unsigned int sharedMemBytes;
  MUstream hStream;
  void **kernelParams;
} MUSA_LAUNCH_PARAMS;
  • where: MUSA_LAUNCH_PARAMS::function specifies the kernel to be launched. All functions must be identical with respect to the compiled code. Note that you can also specify context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then casting to MUfunction. In this case, the context to launch the kernel on be taken from the specified stream MUSA_LAUNCH_PARAMS::hStream. MUSA_LAUNCH_PARAMS::gridDimX is the width of the grid in blocks. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::gridDimY is the height of the grid in blocks. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::gridDimZ is the depth of the grid in blocks. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::blockDimX is the X dimension of each thread block. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::blockDimX is the Y dimension of each thread block. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::blockDimZ is the Z dimension of each thread block. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::sharedMemBytes is the dynamic shared-memory size per thread block in bytes. This must match across all kernels launched. MUSA_LAUNCH_PARAMS::hStream is the handle to the stream to perform the launch in. This cannot be the NULL stream or MU_STREAM_LEGACY or MU_STREAM_PER_THREAD. The MUSA context associated with this stream must match that associated with MUSA_LAUNCH_PARAMS::function. MUSA_LAUNCH_PARAMS::kernelParams is an array of pointers to kernel parameters. If MUSA_LAUNCH_PARAMS::function has N parameters, then MUSA_LAUNCH_PARAMS::kernelParams needs to be an array of N pointers. Each of MUSA_LAUNCH_PARAMS::kernelParams[0] through MUSA_LAUNCH_PARAMS::kernelParams[N-1] must point to a region of memory from which the actual kernel parameter will be copied. The number of kernel parameters and their offsets and sizes do not need to be specified as that information is retrieved directly from the kernel's image.
  • By default, the kernel won't begin execution on any GPU until all prior work in all the specified streams has completed. This behavior can be overridden by specifying the flag MUSA_COOPERATIVE_LAUNCH_MULTI_DEVICE_NO_PRE_LAUNCH_SYNC. When this flag is specified, each kernel will only wait for prior work in the stream corresponding to that GPU to complete before it begins execution.
  • Similarly, by default, any subsequent work pushed in any of the specified streams will not begin execution until the kernels on all GPUs have completed. This behavior can be overridden by specifying the flag MUSA_COOPERATIVE_LAUNCH_MULTI_DEVICE_NO_POST_LAUNCH_SYNC. When this flag is specified, any subsequent work pushed in any of the specified streams will only wait for the kernel launched on the GPU corresponding to that stream to complete before it begins execution.
  • Calling muLaunchCooperativeKernelMultiDevice() sets persistent function state that is the same as function state set through muLaunchKernel API when called individually for each element in launchParamsList.
  • When kernels are launched via muLaunchCooperativeKernelMultiDevice(), the previous block shape, shared size and parameter info associated with each MUSA_LAUNCH_PARAMS::function in launchParamsList is overwritten.
  • Note that to use muLaunchCooperativeKernelMultiDevice(), the kernels must either have been compiled with toolchain version 3.2 or later so that it will contain kernel parameter information, or have no kernel parameters. If either of these conditions is not met, then muLaunchCooperativeKernelMultiDevice() will return MUSA_ERROR_INVALID_IMAGE.
  • Enqueues a host function to run in a stream. The function will be called after currently enqueued work and will block work added after it.
  • The host function must not make any MUSA API calls. Attempting to use a MUSA API may result in MUSA_ERROR_NOT_PERMITTED, but this is not required. The host function must not perform any synchronization that may depend on outstanding MUSA work not mandated to run earlier. Host functions without a mandated order (such as in independent streams) execute in undefined order and may be serialized.
  • For the purposes of Unified Memory, execution makes a number of guarantees: The stream is considered idle for the duration of the function's execution. Thus, for example, the function may always use memory attached to the stream it was enqueued in. The start of execution of the function has the same effect as synchronizing an event recorded in the same stream immediately prior to the function. It thus synchronizes streams which have been "joined" prior to the function. Adding device work to any stream does not have the effect of making the stream active until all preceding host functions and stream callbacks have executed. Thus, for example, a function might use global attached memory even if work has been added to another stream, if the work has been ordered behind the function call with an event. Completion of the function does not cause a stream to become active except as described above. The stream will remain idle if no device work follows the function, and will remain idle across consecutive host functions or stream callbacks without device work in between. Thus, for example, stream synchronization can be done by signaling from a host function at the end of the stream.
  • Note that, in contrast to muStreamAddCallback, the function will not be called in the event of an error in the MUSA context.

Parameters

  • hStream (MUstream): Stream to enqueue function call in
  • fn (MUhostFn): The function to call once preceding stream operations are complete
  • userData (void *): User-specified data to be passed to the function

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_IMAGE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_COOPERATIVE_LAUNCH_TOO_LARGE, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED, MUSA_ERROR_NOT_FOUND
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_IMAGE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_COOPERATIVE_LAUNCH_TOO_LARGE, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

3.21 Execution Control [DEPRECATED]​

muFuncSetSharedMemConfig​

MUresult muFuncSetSharedMemConfig(MUfunction hfunc, MUsharedconfig config)

Description

  • Sets the block-dimensions for the function.
  • Deprecated
  • Specifies the x, y, and z dimensions of the thread blocks that are created when the kernel given by hfunc is launched.
  • Sets through bytes the amount of dynamic shared memory that will be available to each thread block when the kernel given by hfunc is launched.
  • Sets through numbytes the total size in bytes needed by the function parameters of the kernel corresponding to hfunc.
  • Sets an integer parameter that will be specified the next time the kernel corresponding to hfunc will be invoked. offset is a byte offset.
  • Sets a floating-point parameter that will be specified the next time the kernel corresponding to hfunc will be invoked. offset is a byte offset.
  • Copies an arbitrary amount of data (specified in numbytes) from ptr into the parameter space of the kernel corresponding to hfunc. offset is a byte offset.
  • Invokes the kernel f on a 1 x 1 x 1 grid of blocks. The block contains the number of threads specified by a previous call to muFuncSetBlockShape().
  • The block shape, dynamic shared memory size, and parameter information must be set using muFuncSetBlockShape(), muFuncSetSharedSize(), muParamSetSize(), muParamSeti(), muParamSetf(), and muParamSetv() prior to calling this function.
  • Launching a function via muLaunchKernel() invalidates the function's block shape, dynamic shared memory size, and parameter information. After launching via muLaunchKernel, this state must be re-initialized prior to calling this function. Failure to do so results in undefined behavior.
  • Invokes the kernel f on a grid_width x grid_height grid of blocks. Each block contains the number of threads specified by a previous call to muFuncSetBlockShape().
  • Makes the MUSA array or linear memory bound to the texture reference hTexRef available to a device program as a texture. In this version of MUSA, the texture-reference must be obtained via muModuleGetTexRef() and the texunit parameter must be set to MU_PARAM_TR_DEFAULT.
  • On devices with configurable shared memory banks, this function will force all subsequent launches of the specified device function to have the given shared memory bank size configuration. On any given launch of the function, the shared memory configuration of the device will be temporarily changed if needed to suit the function's preferred configuration. Changes in shared memory configuration between subsequent launches of functions, may introduce a device side synchronization point.
  • Any per-function setting of shared memory bank size set via muFuncSetSharedMemConfig will override the context wide setting set with muCtxSetSharedMemConfig.
  • Changing the shared memory bank size will not increase shared memory usage or affect occupancy of kernels, but may have major effects on performance. Larger bank sizes will allow for greater potential bandwidth to shared memory, but will change what kinds of accesses to shared memory will result in bank conflicts.
  • This function will do nothing on devices with fixed shared memory bank size.
  • The supported bank configurations are: MU_SHARED_MEM_CONFIG_DEFAULT_BANK_SIZE: use the context's shared memory configuration when launching this function. MU_SHARED_MEM_CONFIG_FOUR_BYTE_BANK_SIZE: set shared memory bank width to be natively four bytes when launching this function. MU_SHARED_MEM_CONFIG_EIGHT_BYTE_BANK_SIZE: set shared memory bank width to be natively eight bytes when launching this function.

Parameters

  • hfunc (MUfunction): kernel to be given a shared memory config
  • config (MUsharedconfig): requested shared memory configuration

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_LAUNCH_FAILED, MUSA_ERROR_LAUNCH_OUT_OF_RESOURCES, MUSA_ERROR_LAUNCH_TIMEOUT, MUSA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING, MUSA_ERROR_SHARED_OBJECT_INIT_FAILED
  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.
  • In certain cases where mubins are created with no ABI (i.e., using ptxas abi-compile no), this function may serialize kernel launches. The MUSA driver retains asynchronous behavior by growing the per-thread stack as needed per launch and not shrinking it afterwards.

See also

3.22 Graph Management​

Information

  • This module is experimental in MUSA SDK 5.2.0 and is provided for reference only.

muGraphCreate​

MUresult muGraphCreate(MUgraph *phGraph, unsigned int flags)

Description

  • Creates a graph.
  • Creates an empty graph, which is returned via phGraph.

Parameters

  • phGraph (MUgraph *): Returns newly created graph
  • flags (unsigned int): Graph creation flags, must be 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddKernelNode​

MUresult muGraphAddKernelNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_KERNEL_NODE_PARAMS *nodeParams)

Description

  • Creates a kernel execution node and adds it to a graph.
  • Creates a new kernel execution node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • The MUSA_KERNEL_NODE_PARAMS structure is defined as:
typedef struct MUSA_KERNEL_NODE_PARAMS_st {
  MUfunction func;
  unsigned int gridDimX;
  unsigned int gridDimY;
  unsigned int gridDimZ;
  unsigned int blockDimX;
  unsigned int blockDimY;
  unsigned int blockDimZ;
  unsigned int sharedMemBytes;
  void **kernelParams;
  void **extra;
  MUkernelkern;
  MUcontextctx;
} MUSA_KERNEL_NODE_PARAMS;
  • When the graph is launched, the node will invoke kernel func on a (gridDimX x gridDimY x gridDimZ) grid of blocks. Each block contains (blockDimX x blockDimY x blockDimZ) threads.
  • sharedMemBytes sets the amount of dynamic shared memory that will be available to each thread block.
  • Kernel parameters to func can be specified in one of two ways:
    1. Kernel parameters can be specified via kernelParams. If the kernel has N parameters, then kernelParams needs to be an array of N pointers. Each pointer, from kernelParams[0] to kernelParams[N-1], points to the region of memory from which the actual parameter will be copied. The number of kernel parameters and their offsets and sizes do not need to be specified as that information is retrieved directly from the kernel's image.
    1. Kernel parameters for non-cooperative kernels can also be packaged by the application into a single buffer that is passed in via extra. This places the burden on the application of knowing each kernel parameter's size and alignment/padding within the buffer. The extra parameter exists to allow this function to take additional less commonly used arguments. extra specifies a list of names of extra settings and their corresponding values. Each extra setting name is immediately followed by the corresponding value. The list must be terminated with either NULL or MU_LAUNCH_PARAM_END.
  • MU_LAUNCH_PARAM_END, which indicates the end of the extra array; MU_LAUNCH_PARAM_BUFFER_POINTER, which specifies that the next value in extra will be a pointer to a buffer containing all the kernel parameters for launching kernel func; MU_LAUNCH_PARAM_BUFFER_SIZE, which specifies that the next value in extra will be a pointer to a size_t containing the size of the buffer specified with MU_LAUNCH_PARAM_BUFFER_POINTER;
  • The error MUSA_ERROR_INVALID_VALUE will be returned if kernel parameters are specified with both kernelParams and extra (i.e. both kernelParams and extra are non-NULL). MUSA_ERROR_INVALID_VALUE will be returned if extra is used for a cooperative kernel.
  • The kernelParams or extra array, as well as the argument values it points to, are copied during this call.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (const MUSA_KERNEL_NODE_PARAMS *): Parameters for the GPU execution node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphAddKernelNode_v2.
  • Kernels launched using graphs must not use texture and surface references. Reading or writing through any texture or surface reference is undefined behavior. This restriction does not apply to texture and surface objects.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphKernelNodeGetParams​

MUresult muGraphKernelNodeGetParams(MUgraphNode hNode, MUSA_KERNEL_NODE_PARAMS *nodeParams)

Description

  • Returns a kernel node's parameters.
  • Returns the parameters of kernel node hNode in nodeParams. The kernelParams or extra array returned in nodeParams, as well as the argument values it points to, are owned by the node. This memory remains valid until the node is destroyed or its parameters are modified, and should not be modified directly. Use muGraphKernelNodeSetParams to update the parameters of this node.
  • The params will contain either kernelParams or extra, according to which of these was most recently set on the node.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_KERNEL_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphKernelNodeGetParams_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphKernelNodeSetParams​

MUresult muGraphKernelNodeSetParams(MUgraphNode hNode, const MUSA_KERNEL_NODE_PARAMS *nodeParams)

Description

  • Sets a kernel node's parameters.
  • Sets the parameters of kernel node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_KERNEL_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphKernelNodeSetParams_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemcpyNode​

MUresult muGraphAddMemcpyNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEMCPY3D *copyParams, MUcontext ctx)

Description

  • Creates a memcpy node and adds it to a graph.
  • Creates a new memcpy node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will perform the memcpy described by copyParams. See muMemcpy3D() for a description of the structure and its restrictions.
  • Memcpy nodes have some additional restrictions with regards to managed memory, if the system contains at least one device which has a zero value for the device attribute MU_DEVICE_ATTRIBUTE_CONCURRENT_MANAGED_ACCESS. If one or more of the operands refer to managed memory, then using the memory type MU_MEMORYTYPE_UNIFIED is disallowed for those operand(s). The managed memory will be treated as residing on either the host or the device, depending on which memory type is specified.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • copyParams (const MUSA_MEMCPY3D *): Parameters for the memory copy
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemcpyNodeGetParams​

MUresult muGraphMemcpyNodeGetParams(MUgraphNode hNode, MUSA_MEMCPY3D *nodeParams)

Description

  • Returns a memcpy node's parameters.
  • Returns the parameters of memcpy node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEMCPY3D *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemcpyNodeSetParams​

MUresult muGraphMemcpyNodeSetParams(MUgraphNode hNode, const MUSA_MEMCPY3D *nodeParams)

Description

  • Sets a memcpy node's parameters.
  • Sets the parameters of memcpy node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEMCPY3D *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemsetNode​

MUresult muGraphAddMemsetNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEMSET_NODE_PARAMS *memsetParams, MUcontext ctx)

Description

  • Creates a memset node and adds it to a graph.
  • Creates a new memset node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • The element size must be 1, 2, or 4 bytes. When the graph is launched, the node will perform the memset described by memsetParams.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • memsetParams (const MUSA_MEMSET_NODE_PARAMS *): Parameters for the memory set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_CONTEXT

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemsetNodeGetParams​

MUresult muGraphMemsetNodeGetParams(MUgraphNode hNode, MUSA_MEMSET_NODE_PARAMS *nodeParams)

Description

  • Returns a memset node's parameters.
  • Returns the parameters of memset node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEMSET_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemsetNodeSetParams​

MUresult muGraphMemsetNodeSetParams(MUgraphNode hNode, const MUSA_MEMSET_NODE_PARAMS *nodeParams)

Description

  • Sets a memset node's parameters.
  • Sets the parameters of memset node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEMSET_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddHostNode​

MUresult muGraphAddHostNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_HOST_NODE_PARAMS *nodeParams)

Description

  • Creates a host execution node and adds it to a graph.
  • Creates a new CPU execution node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will invoke the specified CPU function. Host nodes are not supported under MPS with pre-Volta GPUs.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (const MUSA_HOST_NODE_PARAMS *): Parameters for the host node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphHostNodeGetParams​

MUresult muGraphHostNodeGetParams(MUgraphNode hNode, MUSA_HOST_NODE_PARAMS *nodeParams)

Description

  • Returns a host node's parameters.
  • Returns the parameters of host node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_HOST_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphHostNodeSetParams​

MUresult muGraphHostNodeSetParams(MUgraphNode hNode, const MUSA_HOST_NODE_PARAMS *nodeParams)

Description

  • Sets a host node's parameters.
  • Sets the parameters of host node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_HOST_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddChildGraphNode​

MUresult muGraphAddChildGraphNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUgraph childGraph)

Description

  • Creates a child graph node and adds it to a graph.
  • Creates a new node which executes an embedded graph, and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • If hGraph contains allocation or free nodes, this call will return an error.
  • The node executes an embedded child graph. The child graph is cloned in this call.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • childGraph (MUgraph): The graph to clone into this node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphChildGraphNodeGetGraph​

MUresult muGraphChildGraphNodeGetGraph(MUgraphNode hNode, MUgraph *phGraph)

Description

  • Gets a handle to the embedded graph of a child graph node.
  • Gets a handle to the embedded graph in a child graph node. This call does not clone the graph. Changes to the graph will be reflected in the node, and the node retains ownership of the graph.
  • Allocation and free nodes cannot be added to the returned graph. Attempting to do so will return an error.

Parameters

  • hNode (MUgraphNode): Node to get the embedded graph for
  • phGraph (MUgraph *): Location to store a handle to the graph

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddEmptyNode​

MUresult muGraphAddEmptyNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies)

Description

  • Creates an empty node and adds it to a graph.
  • Creates a new node which performs no operation, and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • An empty node performs no operation during execution, but can be used for transitive ordering. For example, a phased execution graph with 2 groups of n nodes with a barrier between them can be represented using an empty node and 2*n dependency edges, rather than no empty node and n^2 dependency edges.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddEventRecordNode​

MUresult muGraphAddEventRecordNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUevent event)

Description

  • Creates an event record node and adds it to a graph.
  • Creates a new event record node and adds it to hGraph with numDependencies dependencies specified via dependencies and event specified in event. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • Each launch of the graph will record event to capture execution of the node's dependencies.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • event (MUevent): Event for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphEventRecordNodeGetEvent​

MUresult muGraphEventRecordNodeGetEvent(MUgraphNode hNode, MUevent *event_out)

Description

  • Returns the event associated with an event record node.
  • Returns the event of event record node hNode in event_out.

Parameters

  • hNode (MUgraphNode): Node to get the event for
  • event_out (MUevent *): Pointer to return the event

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphEventRecordNodeSetEvent​

MUresult muGraphEventRecordNodeSetEvent(MUgraphNode hNode, MUevent event)

Description

  • Sets an event record node's event.
  • Sets the event of event record node hNode to event.

Parameters

  • hNode (MUgraphNode): Node to set the event for
  • event (MUevent): Event to use

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddEventWaitNode​

MUresult muGraphAddEventWaitNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUevent event)

Description

  • Creates an event wait node and adds it to a graph.
  • Creates a new event wait node and adds it to hGraph with numDependencies dependencies specified via dependencies and event specified in event. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • The graph node will wait for all work captured in event. See muEventRecord() for details on what is captured by an event. event may be from a different context or device than the launch stream.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • event (MUevent): Event for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphEventWaitNodeGetEvent​

MUresult muGraphEventWaitNodeGetEvent(MUgraphNode hNode, MUevent *event_out)

Description

  • Returns the event associated with an event wait node.
  • Returns the event of event wait node hNode in event_out.

Parameters

  • hNode (MUgraphNode): Node to get the event for
  • event_out (MUevent *): Pointer to return the event

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphEventWaitNodeSetEvent​

MUresult muGraphEventWaitNodeSetEvent(MUgraphNode hNode, MUevent event)

Description

  • Sets an event wait node's event.
  • Sets the event of event wait node hNode to event.

Parameters

  • hNode (MUgraphNode): Node to set the event for
  • event (MUevent): Event to use

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddExternalSemaphoresSignalNode​

MUresult muGraphAddExternalSemaphoresSignalNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *nodeParams)

Description

  • Creates an external semaphore signal node and adds it to a graph.
  • Creates a new external semaphore signal node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • Performs a signal operation on a set of externally allocated semaphore objects when the node is launched. The operation(s) will occur after all of the node's dependencies have completed.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *): Parameters for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExternalSemaphoresSignalNodeGetParams​

MUresult muGraphExternalSemaphoresSignalNodeGetParams(MUgraphNode hNode, MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *params_out)

Description

  • Returns an external semaphore signal node's parameters.
  • Returns the parameters of an external semaphore signal node hNode in params_out. The extSemArray and paramsArray returned in params_out, are owned by the node. This memory remains valid until the node is destroyed or its parameters are modified, and should not be modified directly. Use muGraphExternalSemaphoresSignalNodeSetParams to update the parameters of this node.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • params_out (MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExternalSemaphoresSignalNodeSetParams​

MUresult muGraphExternalSemaphoresSignalNodeSetParams(MUgraphNode hNode, const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *nodeParams)

Description

  • Sets an external semaphore signal node's parameters.
  • Sets the parameters of an external semaphore signal node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddExternalSemaphoresWaitNode​

MUresult muGraphAddExternalSemaphoresWaitNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_EXT_SEM_WAIT_NODE_PARAMS *nodeParams)

Description

  • Creates an external semaphore wait node and adds it to a graph.
  • Creates a new external semaphore wait node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • Performs a wait operation on a set of externally allocated semaphore objects when the node is launched. The node's dependencies will not be launched until the wait operation has completed.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (const MUSA_EXT_SEM_WAIT_NODE_PARAMS *): Parameters for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExternalSemaphoresWaitNodeGetParams​

MUresult muGraphExternalSemaphoresWaitNodeGetParams(MUgraphNode hNode, MUSA_EXT_SEM_WAIT_NODE_PARAMS *params_out)

Description

  • Returns an external semaphore wait node's parameters.
  • Returns the parameters of an external semaphore wait node hNode in params_out. The extSemArray and paramsArray returned in params_out, are owned by the node. This memory remains valid until the node is destroyed or its parameters are modified, and should not be modified directly. Use muGraphExternalSemaphoresSignalNodeSetParams to update the parameters of this node.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • params_out (MUSA_EXT_SEM_WAIT_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExternalSemaphoresWaitNodeSetParams​

MUresult muGraphExternalSemaphoresWaitNodeSetParams(MUgraphNode hNode, const MUSA_EXT_SEM_WAIT_NODE_PARAMS *nodeParams)

Description

  • Sets an external semaphore wait node's parameters.
  • Sets the parameters of an external semaphore wait node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_EXT_SEM_WAIT_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddBatchMemOpNode​

MUresult muGraphAddBatchMemOpNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_BATCH_MEM_OP_NODE_PARAMS *nodeParams)

Description

  • Creates a batch memory operation node and adds it to a graph.
  • Creates a new batch memory operation node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the node is added, the paramArray inside nodeParams is copied and therefore it can be freed after the call returns.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (const MUSA_BATCH_MEM_OP_NODE_PARAMS *): Parameters for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Warning: Improper use of this API may deadlock the application. Synchronization ordering established through this API is not visible to MUSA. MUSA tasks that are (even indirectly) ordered by this API should also have that order expressed with MUSA-visible dependencies such as events. This ensures that the scheduler does not serialize them in an improper order. For more information, see the Stream Memory Operations section in the programming guide(https://docs.mthreads.com/musa/musa-c-programming-guide/index.html).
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphBatchMemOpNodeGetParams​

MUresult muGraphBatchMemOpNodeGetParams(MUgraphNode hNode, MUSA_BATCH_MEM_OP_NODE_PARAMS *nodeParams_out)

Description

  • Returns a batch mem op node's parameters.
  • Returns the parameters of batch mem op node hNode in nodeParams_out. The paramArray returned in nodeParams_out is owned by the node. This memory remains valid until the node is destroyed or its parameters are modified, and should not be modified directly. Use muGraphBatchMemOpNodeSetParams to update the parameters of this node.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams_out (MUSA_BATCH_MEM_OP_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphBatchMemOpNodeSetParams​

MUresult muGraphBatchMemOpNodeSetParams(MUgraphNode hNode, const MUSA_BATCH_MEM_OP_NODE_PARAMS *nodeParams)

Description

  • Sets a batch mem op node's parameters.
  • Sets the parameters of batch mem op node hNode to nodeParams.
  • The paramArray inside nodeParams is copied and therefore it can be freed after the call returns.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_BATCH_MEM_OP_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemAllocNode​

MUresult muGraphAddMemAllocNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUSA_MEM_ALLOC_NODE_PARAMS *nodeParams)

Description

  • Creates an allocation node and adds it to a graph.
  • Creates a new allocation node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • If the allocation is freed in the same graph, by creating a free node using muGraphAddMemFreeNode, the allocation can be accessed by nodes ordered after the allocation node but before the free node. These allocations cannot be freed outside the owning graph, and they can only be freed once in the owning graph.
  • If the allocation is not freed in the same graph, then it can be accessed not only by nodes in the graph which are ordered after the allocation node, but also by stream operations ordered after the graph's execution but before the allocation is freed.
  • Allocations which are not freed in the same graph can be freed by: passing the allocation to muMemFreeAsync or muMemFree; launching a graph with a free node for that allocation; or specifying MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH during instantiation, which makes each launch behave as though it called muMemFreeAsync for every unfreed allocation.
  • It is not possible to free an allocation in both the owning graph and another graph. If the allocation is freed in the same graph, a free node cannot be added to another graph. If the allocation is freed in another graph, a free node can no longer be added to the owning graph.
  • The following restrictions apply to graphs which contain allocation and/or memory free nodes: Nodes and edges of the graph cannot be deleted. The graph cannot be used in a child node. Only one instantiation of the graph may exist at any point in time. The graph cannot be cloned.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (MUSA_MEM_ALLOC_NODE_PARAMS *): Parameters for the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemAllocNodeGetParams​

MUresult muGraphMemAllocNodeGetParams(MUgraphNode hNode, MUSA_MEM_ALLOC_NODE_PARAMS *params_out)

Description

  • Returns a memory alloc node's parameters.
  • Returns the parameters of a memory alloc node hNode in params_out. The poolProps and accessDescs returned in params_out, are owned by the node. This memory remains valid until the node is destroyed. The returned parameters must not be modified.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • params_out (MUSA_MEM_ALLOC_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemFreeNode​

MUresult muGraphAddMemFreeNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUdeviceptr dptr)

Description

  • Creates a memory free node and adds it to a graph.
  • Creates a new memory free node and adds it to hGraph with numDependencies dependencies specified via dependencies and arguments specified in nodeParams. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • The following restrictions apply to graphs which contain allocation and/or memory free nodes: Nodes and edges of the graph cannot be deleted. The graph cannot be used in a child node. Only one instantiation of the graph may exist at any point in time. The graph cannot be cloned.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • dptr (MUdeviceptr): Address of memory to free

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemFreeNodeGetParams​

MUresult muGraphMemFreeNodeGetParams(MUgraphNode hNode, MUdeviceptr *dptr_out)

Description

  • Returns a memory free node's parameters.
  • Returns the address of a memory free node hNode in dptr_out.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • dptr_out (MUdeviceptr *): Pointer to return the device address

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muDeviceGraphMemTrim​

MUresult muDeviceGraphMemTrim(MUdevice device)

Description

  • Free unused memory that was cached on the specified device for use with graphs back to the OS.
  • Blocks which are not in use by a graph that is either currently executing or scheduled to execute are freed back to the operating system.

Parameters

  • device (MUdevice): The device for which cached memory should be freed.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_DEVICE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muDeviceGetGraphMemAttribute​

MUresult muDeviceGetGraphMemAttribute(MUdevice device, MUgraphMem_attribute attr, void *value)

Description

  • Query asynchronous allocation attributes related to graphs.
  • Valid attributes are:
  • MU_GRAPH_MEM_ATTR_USED_MEM_CURRENT: Amount of memory, in bytes, currently associated with graphs MU_GRAPH_MEM_ATTR_USED_MEM_HIGH: High watermark of memory, in bytes, associated with graphs since the last time it was reset. High watermark can only be reset to zero. MU_GRAPH_MEM_ATTR_RESERVED_MEM_CURRENT: Amount of memory, in bytes, currently allocated for use by the MUSA graphs asynchronous allocator. MU_GRAPH_MEM_ATTR_RESERVED_MEM_HIGH: High watermark of memory, in bytes, currently allocated for use by the MUSA graphs asynchronous allocator.

Parameters

  • device (MUdevice): Specifies the scope of the query
  • attr (MUgraphMem_attribute): attribute to get
  • value (void *): retrieved value

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_DEVICE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muDeviceSetGraphMemAttribute​

MUresult muDeviceSetGraphMemAttribute(MUdevice device, MUgraphMem_attribute attr, void *value)

Description

  • Set asynchronous allocation attributes related to graphs.
  • Valid attributes are:
  • MU_GRAPH_MEM_ATTR_USED_MEM_HIGH: High watermark of memory, in bytes, associated with graphs since the last time it was reset. High watermark can only be reset to zero. MU_GRAPH_MEM_ATTR_RESERVED_MEM_HIGH: High watermark of memory, in bytes, currently allocated for use by the MUSA graphs asynchronous allocator.

Parameters

  • device (MUdevice): Specifies the scope of the query
  • attr (MUgraphMem_attribute): attribute to get
  • value (void *): pointer to value to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_DEVICE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muGraphClone​

MUresult muGraphClone(MUgraph *phGraphClone, MUgraph originalGraph)

Description

  • Clones a graph.
  • This function creates a copy of originalGraph and returns it in phGraphClone. All parameters are copied into the cloned graph. The original graph may be modified after this call without affecting the clone.
  • Child graph nodes in the original graph are recursively copied into the clone.

Parameters

  • phGraphClone (MUgraph *): Returns newly created cloned graph
  • originalGraph (MUgraph): Graph to clone

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeFindInClone​

MUresult muGraphNodeFindInClone(MUgraphNode *phNode, MUgraphNode hOriginalNode, MUgraph hClonedGraph)

Description

  • Finds a cloned version of a node.
  • This function returns the node in hClonedGraph corresponding to hOriginalNode in the original graph.
  • hClonedGraph must have been cloned from hOriginalGraph via muGraphClone. hOriginalNode must have been in hOriginalGraph at the time of the call to muGraphClone, and the corresponding cloned node in hClonedGraph must not have been removed. The cloned node is then returned via phClonedNode.

Parameters

  • phNode (MUgraphNode *): Returns handle to the cloned node
  • hOriginalNode (MUgraphNode): Handle to the original node
  • hClonedGraph (MUgraph): Cloned graph to query

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetType​

MUresult muGraphNodeGetType(MUgraphNode hNode, MUgraphNodeType *type)

Description

  • Returns a node's type.
  • Returns the node type of hNode in type.

Parameters

  • hNode (MUgraphNode): Node to query
  • type (MUgraphNodeType *): Pointer to return the node type

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetContainingGraph​

MUresult muGraphNodeGetContainingGraph(MUgraphNode hNode, MUgraph *phGraph)

Description

  • Returns the graph that contains a given graph node.
  • Returns the graph that contains hNode in *phGraph. If hNode is in a child graph, the child graph it is in is returned.

Parameters

  • hNode (MUgraphNode): Node to query
  • phGraph (MUgraph *)

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muGraphNodeGetLocalId​

MUresult muGraphNodeGetLocalId(MUgraphNode hNode, unsigned int *nodeId)

Description

  • Returns the local node id of a given graph node.
  • Returns the node id of hNode in *nodeId. The nodeId matches that referenced by muGraphDebugDotPrint. The local nodeId and graphId together can uniquely identify the node.

Parameters

  • hNode (MUgraphNode): Node to query
  • nodeId (unsigned int *): Pointer to return the nodeId

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muGraphNodeGetToolsId​

MUresult muGraphNodeGetToolsId(MUgraphNode hNode, unsigned long long *toolsNodeId)

Description

  • Returns an id used by tools to identify a given node.

Parameters

  • hNode (MUgraphNode): Node to query
  • toolsNodeId (unsigned long long *)

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muGraphGetId​

MUresult muGraphGetId(MUgraph hGraph, unsigned int *graphId)

Description

  • Returns the id of a given graph.
  • Returns the id of hGraph in *graphId. The value in *graphId will match that referenced by muGraphDebugDotPrint.

Parameters

  • hGraph (MUgraph): Graph to query
  • graphId (unsigned int *)

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muGraphExecGetId​

MUresult muGraphExecGetId(MUgraphExec hGraphExec, unsigned int *graphId)

Description

  • Returns the id of a given graph exec.
  • Returns the id of hGraphExec in *graphId. The value in *graphId will match that referenced by muGraphDebugDotPrint.

Parameters

  • hGraphExec (MUgraphExec): Graph to query
  • graphId (unsigned int *)

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

See also

muGraphGetNodes​

MUresult muGraphGetNodes(MUgraph hGraph, MUgraphNode *nodes, size_t *numNodes)

Description

  • Returns a graph's nodes.
  • Returns a list of hGraph's nodes. nodes may be NULL, in which case this function will return the number of nodes in numNodes. Otherwise, numNodes entries will be filled in. If numNodes is higher than the actual number of nodes, the remaining entries in nodes will be set to NULL, and the number of nodes actually obtained will be returned in numNodes.

Parameters

  • hGraph (MUgraph): Graph to query
  • nodes (MUgraphNode *): Pointer to return the nodes
  • numNodes (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphGetRootNodes​

MUresult muGraphGetRootNodes(MUgraph hGraph, MUgraphNode *rootNodes, size_t *numRootNodes)

Description

  • Returns a graph's root nodes.
  • Returns a list of hGraph's root nodes. rootNodes may be NULL, in which case this function will return the number of root nodes in numRootNodes. Otherwise, numRootNodes entries will be filled in. If numRootNodes is higher than the actual number of root nodes, the remaining entries in rootNodes will be set to NULL, and the number of nodes actually obtained will be returned in numRootNodes.

Parameters

  • hGraph (MUgraph): Graph to query
  • rootNodes (MUgraphNode *): Pointer to return the root nodes
  • numRootNodes (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphGetEdges​

MUresult muGraphGetEdges(MUgraph hGraph, MUgraphNode *from, MUgraphNode *to, size_t *numEdges)

Description

  • Returns a graph's dependency edges.
  • Returns a list of hGraph's dependency edges. Edges are returned via corresponding indices in from and to; that is, the node in to[i] has a dependency on the node in from[i]. from and to may both be NULL, in which case this function only returns the number of edges in numEdges. Otherwise, numEdges entries will be filled in. If numEdges is higher than the actual number of edges, the remaining entries in from and to will be set to NULL, and the number of edges actually returned will be written to numEdges.

Parameters

  • hGraph (MUgraph): Graph to get the edges from
  • from (MUgraphNode *): Location to return edge endpoints
  • to (MUgraphNode *): Location to return edge endpoints
  • numEdges (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphGetEdges_v2​

MUresult muGraphGetEdges_v2(MUgraph hGraph, MUgraphNode *from, MUgraphNode *to, MUgraphEdgeData *edgeData, size_t *numEdges)

Description

  • Returns a graph's dependency edges (12.3+)
  • Returns a list of hGraph's dependency edges. Edges are returned via corresponding indices in from, to and edgeData; that is, the node in to[i] has a dependency on the node in from[i] with data edgeData[i]. from and to may both be NULL, in which case this function only returns the number of edges in numEdges. Otherwise, numEdges entries will be filled in. If numEdges is higher than the actual number of edges, the remaining entries in from and to will be set to NULL, and the number of edges actually returned will be written to numEdges. edgeData may alone be NULL, in which case the edges must all have default (zeroed) edge data. Attempting a lossy query via NULL edgeData will result in MUSA_ERROR_LOSSY_QUERY. If edgeData is non-NULL then from and to must be as well.

Parameters

  • hGraph (MUgraph): Graph to get the edges from
  • from (MUgraphNode *): Location to return edge endpoints
  • to (MUgraphNode *): Location to return edge endpoints
  • edgeData (MUgraphEdgeData *): Optional location to return edge data
  • numEdges (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_LOSSY_QUERY, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetDependencies​

MUresult muGraphNodeGetDependencies(MUgraphNode hNode, MUgraphNode *dependencies, size_t *numDependencies)

Description

  • Returns a node's dependencies.
  • Returns a list of node's dependencies. dependencies may be NULL, in which case this function will return the number of dependencies in numDependencies. Otherwise, numDependencies entries will be filled in. If numDependencies is higher than the actual number of dependencies, the remaining entries in dependencies will be set to NULL, and the number of nodes actually obtained will be returned in numDependencies.

Parameters

  • hNode (MUgraphNode): Node to query
  • dependencies (MUgraphNode *): Pointer to return the dependencies
  • numDependencies (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetDependencies_v2​

MUresult muGraphNodeGetDependencies_v2(MUgraphNode hNode, MUgraphNode *dependencies, MUgraphEdgeData *edgeData, size_t *numDependencies)

Description

  • Returns a node's dependencies (12.3+)
  • Returns a list of node's dependencies. dependencies may be NULL, in which case this function will return the number of dependencies in numDependencies. Otherwise, numDependencies entries will be filled in. If numDependencies is higher than the actual number of dependencies, the remaining entries in dependencies will be set to NULL, and the number of nodes actually obtained will be returned in numDependencies.
  • Note that if an edge has non-zero (non-default) edge data and edgeData is NULL, this API will return MUSA_ERROR_LOSSY_QUERY. If edgeData is non-NULL, then dependencies must be as well.

Parameters

  • hNode (MUgraphNode): Node to query
  • dependencies (MUgraphNode *): Pointer to return the dependencies
  • edgeData (MUgraphEdgeData *): Optional array to return edge data for each dependency
  • numDependencies (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_LOSSY_QUERY, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetDependentNodes​

MUresult muGraphNodeGetDependentNodes(MUgraphNode hNode, MUgraphNode *dependentNodes, size_t *numDependentNodes)

Description

  • Returns a node's dependent nodes.
  • Returns a list of node's dependent nodes. dependentNodes may be NULL, in which case this function will return the number of dependent nodes in numDependentNodes. Otherwise, numDependentNodes entries will be filled in. If numDependentNodes is higher than the actual number of dependent nodes, the remaining entries in dependentNodes will be set to NULL, and the number of nodes actually obtained will be returned in numDependentNodes.

Parameters

  • hNode (MUgraphNode): Node to query
  • dependentNodes (MUgraphNode *): Pointer to return the dependent nodes
  • numDependentNodes (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetDependentNodes_v2​

MUresult muGraphNodeGetDependentNodes_v2(MUgraphNode hNode, MUgraphNode *dependentNodes, MUgraphEdgeData *edgeData, size_t *numDependentNodes)

Description

  • Returns a node's dependent nodes (12.3+)
  • Returns a list of node's dependent nodes. dependentNodes may be NULL, in which case this function will return the number of dependent nodes in numDependentNodes. Otherwise, numDependentNodes entries will be filled in. If numDependentNodes is higher than the actual number of dependent nodes, the remaining entries in dependentNodes will be set to NULL, and the number of nodes actually obtained will be returned in numDependentNodes.
  • Note that if an edge has non-zero (non-default) edge data and edgeData is NULL, this API will return MUSA_ERROR_LOSSY_QUERY. If edgeData is non-NULL, then dependentNodes must be as well.

Parameters

  • hNode (MUgraphNode): Node to query
  • dependentNodes (MUgraphNode *): Pointer to return the dependent nodes
  • edgeData (MUgraphEdgeData *): Optional pointer to return edge data for dependent nodes
  • numDependentNodes (size_t *): See description

Returns

  • MUSA_SUCCESS, MUSA_ERROR_LOSSY_QUERY, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddDependencies​

MUresult muGraphAddDependencies(MUgraph hGraph, const MUgraphNode *from, const MUgraphNode *to, size_t numDependencies)

Description

  • Adds dependency edges to a graph.
  • The number of dependencies to be added is defined by numDependencies Elements in from and to at corresponding indices define a dependency. Each node in from and to must belong to hGraph.
  • If numDependencies is 0, elements in from and to will be ignored. Specifying an existing dependency will return an error.

Parameters

  • hGraph (MUgraph): Graph to which dependencies are added
  • from (const MUgraphNode *): Array of nodes that provide the dependencies
  • to (const MUgraphNode *): Array of dependent nodes
  • numDependencies (size_t): Number of dependencies to be added

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddDependencies_v2​

MUresult muGraphAddDependencies_v2(MUgraph hGraph, const MUgraphNode *from, const MUgraphNode *to, const MUgraphEdgeData *edgeData, size_t numDependencies)

Description

  • Adds dependency edges to a graph (12.3+)
  • The number of dependencies to be added is defined by numDependencies Elements in from and to at corresponding indices define a dependency. Each node in from and to must belong to hGraph.
  • If numDependencies is 0, elements in from and to will be ignored. Specifying an existing dependency will return an error.

Parameters

  • hGraph (MUgraph): Graph to which dependencies are added
  • from (const MUgraphNode *): Array of nodes that provide the dependencies
  • to (const MUgraphNode *): Array of dependent nodes
  • edgeData (const MUgraphEdgeData *): Optional array of edge data. If NULL, default (zeroed) edge data is assumed.
  • numDependencies (size_t): Number of dependencies to be added

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphRemoveDependencies​

MUresult muGraphRemoveDependencies(MUgraph hGraph, const MUgraphNode *from, const MUgraphNode *to, size_t numDependencies)

Description

  • Removes dependency edges from a graph.
  • The number of dependencies to be removed is defined by numDependencies. Elements in from and to at corresponding indices define a dependency. Each node in from and to must belong to hGraph.
  • If numDependencies is 0, elements in from and to will be ignored. Specifying a non-existing dependency will return an error.
  • Dependencies cannot be removed from graphs which contain allocation or free nodes. Any attempt to do so will return an error.

Parameters

  • hGraph (MUgraph): Graph from which to remove dependencies
  • from (const MUgraphNode *): Array of nodes that provide the dependencies
  • to (const MUgraphNode *): Array of dependent nodes
  • numDependencies (size_t): Number of dependencies to be removed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphRemoveDependencies_v2​

MUresult muGraphRemoveDependencies_v2(MUgraph hGraph, const MUgraphNode *from, const MUgraphNode *to, const MUgraphEdgeData *edgeData, size_t numDependencies)

Description

  • Removes dependency edges from a graph (12.3+)
  • The number of dependencies to be removed is defined by numDependencies. Elements in from and to at corresponding indices define a dependency. Each node in from and to must belong to hGraph.
  • If numDependencies is 0, elements in from and to will be ignored. Specifying an edge that does not exist in the graph, with data matching edgeData, results in an error. edgeData is nullable, which is equivalent to passing default (zeroed) data for each edge.
  • Dependencies cannot be removed from graphs which contain allocation or free nodes. Any attempt to do so will return an error.

Parameters

  • hGraph (MUgraph): Graph from which to remove dependencies
  • from (const MUgraphNode *): Array of nodes that provide the dependencies
  • to (const MUgraphNode *): Array of dependent nodes
  • edgeData (const MUgraphEdgeData *): Optional array of edge data. If NULL, edge data is assumed to be default (zeroed).
  • numDependencies (size_t): Number of dependencies to be removed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphDestroyNode​

MUresult muGraphDestroyNode(MUgraphNode hNode)

Description

  • Remove a node from the graph.
  • Removes hNode from its graph. This operation also severs any dependencies of other nodes on hNode and vice versa.
  • Nodes which belong to a graph which contains allocation or free nodes cannot be destroyed. Any attempt to do so will return an error.

Parameters

  • hNode (MUgraphNode): Node to remove

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphInstantiate​

MUresult muGraphInstantiate(MUgraphExec *phGraphExec, MUgraph hGraph, unsigned long long flags)

Description

  • Creates an executable graph from a graph.
  • Instantiates hGraph as an executable graph. The graph is validated for any structural constraints or intra-node constraints which were not previously validated. If instantiation is successful, a handle to the instantiated graph is returned in phGraphExec.
  • The flags parameter controls the behavior of instantiation and subsequent graph launches. Valid flags are:
  • MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH, which configures a graph containing memory allocation nodes to automatically free any unfreed memory allocations before the graph is relaunched. MUSA_GRAPH_INSTANTIATE_FLAG_DEVICE_LAUNCH, which configures the graph for launch from the device. If this flag is passed, the executable graph handle returned can be used to launch the graph from both the host and device. This flag can only be used on platforms which support unified addressing. This flag cannot be used in conjunction with MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH. MUSA_GRAPH_INSTANTIATE_FLAG_USE_NODE_PRIORITY, which causes the graph to use the priorities from the per-node attributes rather than the priority of the launch stream during execution. Note that priorities are only available on kernel nodes, and are copied from stream priority during stream capture.
  • If hGraph contains any allocation or free nodes, there can be at most one executable graph in existence for that graph at a time. An attempt to instantiate a second executable graph before destroying the first with muGraphExecDestroy will result in an error. The same also applies if hGraph contains any device-updatable kernel nodes.
  • If hGraph contains kernels which call device-side musaGraphLaunch() from multiple contexts, this will result in an error.
  • Graphs instantiated for launch on the device have additional restrictions which do not apply to host graphs:
  • The graph's nodes must reside on a single context. The graph can only contain kernel nodes, memcpy nodes, memset nodes, and child graph nodes. The graph cannot be empty and must contain at least one kernel, memcpy, or memset node. Operation-specific restrictions are outlined below. Kernel nodes: Use of MUSA Dynamic Parallelism is not permitted. Cooperative launches are permitted as long as MPS is not in use. Memcpy nodes: Only copies involving device memory and/or pinned device-mapped host memory are permitted. Copies involving MUSA arrays are not permitted. Both operands must be accessible from the current context, and the current context must match the context of other nodes in the graph.

Parameters

  • phGraphExec (MUgraphExec *): Returns instantiated graph
  • hGraph (MUgraph): Graph to instantiate
  • flags (unsigned long long): Flags to control instantiation. See MUgraphInstantiate_flags.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphInstantiateWithFlags, muGraphInstantiate_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphInstantiateWithParams​

MUresult muGraphInstantiateWithParams(MUgraphExec *phGraphExec, MUgraph hGraph, MUSA_GRAPH_INSTANTIATE_PARAMS *instantiateParams)

Description

  • Creates an executable graph from a graph.
  • Instantiates hGraph as an executable graph according to the instantiateParams structure. The graph is validated for any structural constraints or intra-node constraints which were not previously validated. If instantiation is successful, a handle to the instantiated graph is returned in phGraphExec.
  • instantiateParams controls the behavior of instantiation and subsequent graph launches, as well as returning more detailed information in the event of an error. MUSA_GRAPH_INSTANTIATE_PARAMS is defined as:
typedef struct  {
  muuint64_t flags;
  MUstream hUploadStream;
  MUgraphNodehErrNode_out;
  MUgraphInstantiateResultresult_out;
} MUSA_GRAPH_INSTANTIATE_PARAMS;
  • The flags field controls the behavior of instantiation and subsequent graph launches. Valid flags are:
  • MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH, which configures a graph containing memory allocation nodes to automatically free any unfreed memory allocations before the graph is relaunched. MUSA_GRAPH_INSTANTIATE_FLAG_UPLOAD, which will perform an upload of the graph into hUploadStream once the graph has been instantiated. MUSA_GRAPH_INSTANTIATE_FLAG_DEVICE_LAUNCH, which configures the graph for launch from the device. If this flag is passed, the executable graph handle returned can be used to launch the graph from both the host and device. This flag can only be used on platforms which support unified addressing. This flag cannot be used in conjunction with MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH. MUSA_GRAPH_INSTANTIATE_FLAG_USE_NODE_PRIORITY, which causes the graph to use the priorities from the per-node attributes rather than the priority of the launch stream during execution. Note that priorities are only available on kernel nodes, and are copied from stream priority during stream capture.
  • If hGraph contains any allocation or free nodes, there can be at most one executable graph in existence for that graph at a time. An attempt to instantiate a second executable graph before destroying the first with muGraphExecDestroy will result in an error. The same also applies if hGraph contains any device-updatable kernel nodes.
  • If hGraph contains kernels which call device-side musaGraphLaunch() from multiple contexts, this will result in an error.
  • Graphs instantiated for launch on the device have additional restrictions which do not apply to host graphs:
  • The graph's nodes must reside on a single context. The graph can only contain kernel nodes, memcpy nodes, memset nodes, and child graph nodes. The graph cannot be empty and must contain at least one kernel, memcpy, or memset node. Operation-specific restrictions are outlined below. Kernel nodes: Use of MUSA Dynamic Parallelism is not permitted. Cooperative launches are permitted as long as MPS is not in use. Memcpy nodes: Only copies involving device memory and/or pinned device-mapped host memory are permitted. Copies involving MUSA arrays are not permitted. Both operands must be accessible from the current context, and the current context must match the context of other nodes in the graph.
  • In the event of an error, the result_out and hErrNode_out fields will contain more information about the nature of the error. Possible error reporting includes:
  • MUSA_GRAPH_INSTANTIATE_ERROR, if passed an invalid value or if an unexpected error occurred which is described by the return value of the function. hErrNode_out will be set to NULL. MUSA_GRAPH_INSTANTIATE_INVALID_STRUCTURE, if the graph structure is invalid. hErrNode_out will be set to one of the offending nodes. MUSA_GRAPH_INSTANTIATE_NODE_OPERATION_NOT_SUPPORTED, if the graph is instantiated for device launch but contains a node of an unsupported node type, or a node which performs unsupported operations, such as use of MUSA dynamic parallelism within a kernel node. hErrNode_out will be set to this node. MUSA_GRAPH_INSTANTIATE_MULTIPLE_CTXS_NOT_SUPPORTED, if the graph is instantiated for device launch but a node’s context differs from that of another node. This error can also be returned if a graph is not instantiated for device launch and it contains kernels which call device-side musaGraphLaunch() from multiple contexts. hErrNode_out will be set to this node.
  • If instantiation is successful, result_out will be set to MUSA_GRAPH_INSTANTIATE_SUCCESS, and hErrNode_out will be set to NULL.

Parameters

  • phGraphExec (MUgraphExec *): Returns instantiated graph
  • hGraph (MUgraph): Graph to instantiate
  • instantiateParams (MUSA_GRAPH_INSTANTIATE_PARAMS *): Instantiation parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecGetFlags​

MUresult muGraphExecGetFlags(MUgraphExec hGraphExec, muuint64_t *flags)

Description

  • Query the instantiation flags of an executable graph.
  • Returns the flags that were passed to instantiation for the given executable graph. MUSA_GRAPH_INSTANTIATE_FLAG_UPLOAD will not be returned by this API as it does not affect the resulting executable graph.

Parameters

  • hGraphExec (MUgraphExec): The executable graph to query
  • flags (muuint64_t *): Returns the instantiation flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecKernelNodeSetParams​

MUresult muGraphExecKernelNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_KERNEL_NODE_PARAMS *nodeParams)

Description

  • Sets the parameters for a kernel node in the given graphExec.
  • Sets the parameters of a kernel node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • hNode must not have been removed from the original graph. All nodeParams fields may change, but the following restrictions apply to func updates:
  • The owning context of the function cannot change. A node whose function originally did not use MUSA dynamic parallelism cannot be updated to a function which uses CDP A node whose function originally did not make device-side update calls cannot be updated to a function which makes device-side update calls. If hGraphExec was not instantiated for device launch, a node whose function originally did not use device-side musaGraphLaunch() cannot be updated to a function which uses device-side musaGraphLaunch() unless the node resides on the same context as nodes which contained such calls at instantiate-time. If no such calls were present at instantiation, these updates cannot be performed at all.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • If hNode is a device-updatable kernel node, the next upload/launch of hGraphExec will overwrite any previous device-side updates. Additionally, applying host updates to a device-updatable kernel node while it is being updated from the device will result in undefined behavior.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): kernel node from the graph from which graphExec was instantiated
  • nodeParams (const MUSA_KERNEL_NODE_PARAMS *): Updated Parameters to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphExecKernelNodeSetParams_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemcpyNodeSetParams​

MUresult muGraphExecMemcpyNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEMCPY3D *copyParams, MUcontext ctx)

Description

  • Sets the parameters for a memcpy node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained copyParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The source and destination memory in copyParams must be allocated from the same contexts as the original source and destination memory. Both the instantiation-time memory operands and the memory operands in copyParams must be 1-dimensional. Zero-length operations are not supported.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • Returns MUSA_ERROR_INVALID_VALUE if the memory operands' mappings changed or either the original or new memory operands are multidimensional.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memcpy node from the graph which was used to instantiate graphExec
  • copyParams (const MUSA_MEMCPY3D *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemsetNodeSetParams​

MUresult muGraphExecMemsetNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEMSET_NODE_PARAMS *memsetParams, MUcontext ctx)

Description

  • Sets the parameters for a memset node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained memsetParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • Zero sized operations are not supported.
  • The new destination pointer in memsetParams must be to the same kind of allocation as the original destination pointer and have the same context association and device mapping as the original destination pointer.
  • Both the value and pointer address may be updated. Changing other aspects of the memset (width, height, element size or pitch) may cause the update to be rejected. Specifically, for 2d memsets, all dimension changes are rejected. For 1d memsets, changes in height are explicitly rejected and other changes are oportunistically allowed if the resulting work maps onto the work resources already allocated for the node.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memset node from the graph which was used to instantiate graphExec
  • memsetParams (const MUSA_MEMSET_NODE_PARAMS *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecHostNodeSetParams​

MUresult muGraphExecHostNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_HOST_NODE_PARAMS *nodeParams)

Description

  • Sets the parameters for a host node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained nodeParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Host node from the graph which was used to instantiate graphExec
  • nodeParams (const MUSA_HOST_NODE_PARAMS *): The updated parameters to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecChildGraphNodeSetParams​

MUresult muGraphExecChildGraphNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, MUgraph childGraph)

Description

  • Updates node parameters in the child graph node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though the nodes contained in hNode's graph had the parameters contained in childGraph's nodes at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • The topology of childGraph, as well as the node insertion order, must match that of the graph contained in hNode. See muGraphExecUpdate() for a list of restrictions on what can be updated in an instantiated graph. The update is recursive, so child graph nodes contained within the top level child graph will also be updated.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Host node from the graph which was used to instantiate graphExec
  • childGraph (MUgraph): The graph supplying the updated parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecEventRecordNodeSetEvent​

MUresult muGraphExecEventRecordNodeSetEvent(MUgraphExec hGraphExec, MUgraphNode hNode, MUevent event)

Description

  • Sets the event for an event record node in the given graphExec.
  • Sets the event of an event record node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): event record node from the graph from which graphExec was instantiated
  • event (MUevent): Updated event to use

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecEventWaitNodeSetEvent​

MUresult muGraphExecEventWaitNodeSetEvent(MUgraphExec hGraphExec, MUgraphNode hNode, MUevent event)

Description

  • Sets the event for an event wait node in the given graphExec.
  • Sets the event of an event wait node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): event wait node from the graph from which graphExec was instantiated
  • event (MUevent): Updated event to use

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecExternalSemaphoresSignalNodeSetParams​

MUresult muGraphExecExternalSemaphoresSignalNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *nodeParams)

Description

  • Sets the parameters for an external semaphore signal node in the given graphExec.
  • Sets the parameters of an external semaphore signal node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • hNode must not have been removed from the original graph.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • Changing nodeParams->numExtSems is not supported.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): semaphore signal node from the graph from which graphExec was instantiated
  • nodeParams (const MUSA_EXT_SEM_SIGNAL_NODE_PARAMS *): Updated Parameters to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecExternalSemaphoresWaitNodeSetParams​

MUresult muGraphExecExternalSemaphoresWaitNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_EXT_SEM_WAIT_NODE_PARAMS *nodeParams)

Description

  • Sets the parameters for an external semaphore wait node in the given graphExec.
  • Sets the parameters of an external semaphore wait node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • hNode must not have been removed from the original graph.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • Changing nodeParams->numExtSems is not supported.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): semaphore wait node from the graph from which graphExec was instantiated
  • nodeParams (const MUSA_EXT_SEM_WAIT_NODE_PARAMS *): Updated Parameters to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeSetEnabled​

MUresult muGraphNodeSetEnabled(MUgraphExec hGraphExec, MUgraphNode hNode, unsigned int isEnabled)

Description

  • Enables or disables the specified node in the given graphExec.
  • Sets hNode to be either enabled or disabled. Disabled nodes are functionally equivalent to empty nodes until they are reenabled. Existing node parameters are not affected by disabling/enabling the node.
  • The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • hNode must not have been removed from the original graph.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • If hNode is a device-updatable kernel node, the next upload/launch of hGraphExec will overwrite any previous device-side updates. Additionally, applying host updates to a device-updatable kernel node while it is being updated from the device will result in undefined behavior.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Node from the graph from which graphExec was instantiated
  • isEnabled (unsigned int): Node is enabled if != 0, otherwise the node is disabled

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Currently only kernel, memset and memcpy nodes are supported.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetEnabled​

MUresult muGraphNodeGetEnabled(MUgraphExec hGraphExec, MUgraphNode hNode, unsigned int *isEnabled)

Description

  • Query whether a node in the given graphExec is enabled.
  • Sets isEnabled to 1 if hNode is enabled, or 0 if hNode is disabled.
  • The node is identified by the corresponding node hNode in the non-executable graph, from which the executable graph was instantiated.
  • hNode must not have been removed from the original graph.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Node from the graph from which graphExec was instantiated
  • isEnabled (unsigned int *): Location to return the enabled status of the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Currently only kernel, memset and memcpy nodes are supported.
  • This function will not reflect device-side updates for device-updatable kernel nodes.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphUpload​

MUresult muGraphUpload(MUgraphExec hGraphExec, MUstream hStream)

Description

  • Uploads an executable graph in a stream.
  • Uploads hGraphExec to the device in hStream without executing it. Uploads of the same hGraphExec will be serialized. Each upload is ordered behind both any previous work in hStream and any previous launches of hGraphExec. Uses memory cached by stream to back the allocations owned by hGraphExec.

Parameters

  • hGraphExec (MUgraphExec): Executable graph to upload
  • hStream (MUstream): Stream in which to upload the graph

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphLaunch​

MUresult muGraphLaunch(MUgraphExec hGraphExec, MUstream hStream)

Description

  • Launches an executable graph in a stream.
  • Executes hGraphExec in hStream. Only one instance of hGraphExec may be executing at a time. Each launch is ordered behind both any previous work in hStream and any previous launches of hGraphExec. To execute a graph concurrently, it must be instantiated multiple times into multiple executable graphs.
  • If any allocations created by hGraphExec remain unfreed (from a previous launch) and hGraphExec was not instantiated with MUSA_GRAPH_INSTANTIATE_FLAG_AUTO_FREE_ON_LAUNCH, the launch will fail with MUSA_ERROR_INVALID_VALUE.

Parameters

  • hGraphExec (MUgraphExec): Executable graph to launch
  • hStream (MUstream): Stream in which to launch the graph

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecDestroy​

MUresult muGraphExecDestroy(MUgraphExec hGraphExec)

Description

  • Destroys an executable graph.
  • Destroys the executable graph specified by hGraphExec, as well as all of its executable nodes. If the executable graph is in-flight, it will not be terminated, but rather freed asynchronously on completion.

Parameters

  • hGraphExec (MUgraphExec): Executable graph to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphDestroy​

MUresult muGraphDestroy(MUgraph hGraph)

Description

  • Destroys a graph.
  • Destroys the graph specified by hGraph, as well as all of its nodes.

Parameters

  • hGraph (MUgraph): Graph to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecUpdate​

MUresult muGraphExecUpdate(MUgraphExec hGraphExec, MUgraph hGraph, MUgraphExecUpdateResultInfo *resultInfo)

Description

  • Check whether an executable graph can be updated with a graph and perform the update if possible.
  • Updates the node parameters in the instantiated graph specified by hGraphExec with the node parameters in a topologically identical graph specified by hGraph.
  • Limitations:
  • Kernel nodes: The owning context of the function cannot change. A node whose function originally did not use MUSA dynamic parallelism cannot be updated to a function which uses CDP. A node whose function originally did not make device-side update calls cannot be updated to a function which makes device-side update calls. A cooperative node cannot be updated to a non-cooperative node, and vice-versa. If the graph was instantiated with MUSA_GRAPH_INSTANTIATE_FLAG_USE_NODE_PRIORITY, the priority attribute cannot change. Equality is checked on the originally requested priority values, before they are clamped to the device's supported range. If hGraphExec was not instantiated for device launch, a node whose function originally did not use device-side musaGraphLaunch() cannot be updated to a function which uses device-side musaGraphLaunch() unless the node resides on the same context as nodes which contained such calls at instantiate-time. If no such calls were present at instantiation, these updates cannot be performed at all. Neither hGraph nor hGraphExec may contain device-updatable kernel nodes. Memset and memcpy nodes: The MUSA device(s) to which the operand(s) was allocated/mapped cannot change. The source/destination memory must be allocated from the same contexts as the original source/destination memory. For 2d memsets, only address and assinged value may be updated. For 1d memsets, updating dimensions is also allowed, but may fail if the resulting operation doesn't map onto the work resources already allocated for the node. Additional memcpy node restrictions: Changing either the source or destination memory type(i.e. MU_MEMORYTYPE_DEVICE, MU_MEMORYTYPE_ARRAY, etc.) is not supported. External semaphore wait nodes and record nodes: Changing the number of semaphores is not supported. Conditional nodes: Changing node parameters is not supported. Changeing parameters of nodes within the conditional body graph is subject to the rules above. Conditional handle flags and default values are updated as part of the graph update.
  • Note: The API may add further restrictions in future releases. The return code should always be checked.
  • muGraphExecUpdate sets the result member of resultInfo to MU_GRAPH_EXEC_UPDATE_ERROR_TOPOLOGY_CHANGED under the following conditions: The count of nodes directly in hGraphExec and hGraph differ, in which case resultInfo->errorNode is set to NULL. hGraph has more exit nodes than hGraph, in which case resultInfo->errorNode is set to one of the exit nodes in hGraph. A node in hGraph has a different number of dependencies than the node from hGraphExec it is paired with, in which case resultInfo->errorNode is set to the node from hGraph. A node in hGraph has a dependency that does not match with the corresponding dependency of the paired node from hGraphExec. resultInfo->errorNode will be set to the node from hGraph. resultInfo->errorFromNode will be set to the mismatched dependency. The dependencies are paired based on edge order and a dependency does not match when the nodes are already paired based on other edges examined in the graph.
  • muGraphExecUpdate sets the result member of resultInfo to: MU_GRAPH_EXEC_UPDATE_ERROR if passed an invalid value. MU_GRAPH_EXEC_UPDATE_ERROR_TOPOLOGY_CHANGED if the graph topology changed MU_GRAPH_EXEC_UPDATE_ERROR_NODE_TYPE_CHANGED if the type of a node changed, in which case hErrorNode_out is set to the node from hGraph. MU_GRAPH_EXEC_UPDATE_ERROR_UNSUPPORTED_FUNCTION_CHANGE if the function changed in an unsupported way(see note above), in which case hErrorNode_out is set to the node from hGraph MU_GRAPH_EXEC_UPDATE_ERROR_PARAMETERS_CHANGED if any parameters to a node changed in a way that is not supported, in which case hErrorNode_out is set to the node from hGraph. MU_GRAPH_EXEC_UPDATE_ERROR_ATTRIBUTES_CHANGED if any attributes of a node changed in a way that is not supported, in which case hErrorNode_out is set to the node from hGraph. MU_GRAPH_EXEC_UPDATE_ERROR_NOT_SUPPORTED if something about a node is unsupported, like the node's type or configuration, in which case hErrorNode_out is set to the node from hGraph
  • If the update fails for a reason not listed above, the result member of resultInfo will be set to MU_GRAPH_EXEC_UPDATE_ERROR. If the update succeeds, the result member will be set to MU_GRAPH_EXEC_UPDATE_SUCCESS.
  • muGraphExecUpdate returns MUSA_SUCCESS when the updated was performed successfully. It returns MUSA_ERROR_GRAPH_EXEC_UPDATE_FAILURE if the graph update was not performed because it included changes which violated constraints specific to instantiated graph update.

Parameters

  • hGraphExec (MUgraphExec): The instantiated graph to be updated
  • hGraph (MUgraph): The graph containing the updated parameters
  • resultInfo (MUgraphExecUpdateResultInfo *): the error info structure

Returns

  • MUSA_SUCCESS, MUSA_ERROR_GRAPH_EXEC_UPDATE_FAILURE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Additional exported symbol names in scope: muGraphExecUpdate_v2.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphKernelNodeCopyAttributes​

MUresult muGraphKernelNodeCopyAttributes(MUgraphNode dst, MUgraphNode src)

Description

  • Copies attributes from source node to destination node.
  • Copies attributes from source node src to destination node dst. Both node must have the same context.

Parameters

  • dst (MUgraphNode): Destination node
  • src (MUgraphNode): Source node For list of attributes see MUkernelNodeAttrID

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muGraphKernelNodeGetAttribute​

MUresult muGraphKernelNodeGetAttribute(MUgraphNode hNode, MUkernelNodeAttrID attr, MUkernelNodeAttrValue *value_out)

Description

  • Queries node attribute.
  • Queries attribute attr from node hNode and stores it in corresponding member of value_out.

Parameters

  • hNode (MUgraphNode)
  • attr (MUkernelNodeAttrID)
  • value_out (MUkernelNodeAttrValue *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muGraphKernelNodeSetAttribute​

MUresult muGraphKernelNodeSetAttribute(MUgraphNode hNode, MUkernelNodeAttrID attr, const MUkernelNodeAttrValue *value)

Description

  • Sets node attribute.
  • Sets attribute attr on node hNode from corresponding attribute of value.

Parameters

  • hNode (MUgraphNode)
  • attr (MUkernelNodeAttrID)
  • value (const MUkernelNodeAttrValue *)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.

See also

  • MUaccessPolicyWindow

muGraphDebugDotPrint​

MUresult muGraphDebugDotPrint(MUgraph hGraph, const char *path, unsigned int flags)

Description

  • Write a DOT file describing graph structure.
  • Using the provided hGraph, write to path a DOT formatted description of the graph. By default this includes the graph topology, node types, node id, kernel names and memcpy direction. flags can be specified to write more detailed information about each node type such as parameter values, kernel attributes, node and function handles.

Parameters

  • hGraph (MUgraph): The graph to create a DOT file from
  • path (const char *): The path to write the DOT file to
  • flags (unsigned int): Flags from MUgraphDebugDot_flags for specifying which additional node information to write

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OPERATING_SYSTEM

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

muUserObjectCreate​

MUresult muUserObjectCreate(MUuserObject *object_out, void *ptr, MUhostFn destroy, unsigned int initialRefcount, unsigned int flags)

Description

  • Create a user object.
  • Create a user object with the specified destructor callback and initial reference count. The initial references are owned by the caller.
  • Destructor callbacks cannot make MUSA API calls and should avoid blocking behavior, as they are executed by a shared internal thread. Another thread may be signaled to perform such actions, if it does not block forward progress of tasks scheduled through MUSA.
  • See MUSA User Objects in the MUSA C++ Programming Guide for more information on user objects.

Parameters

  • object_out (MUuserObject *): Location to return the user object handle
  • ptr (void *): The pointer to pass to the destroy function
  • destroy (MUhostFn): Callback to free the user object when it is no longer in use
  • initialRefcount (unsigned int): The initial refcount to create the object with, typically 1. The initial references are owned by the calling thread.
  • flags (unsigned int): Currently it is required to pass MU_USER_OBJECT_NO_DESTRUCTOR_SYNC, which is the only defined flag. This indicates that the destroy callback cannot be waited on by any MUSA API. Users requiring synchronization of the callback should signal its completion manually.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muUserObjectRetain​

MUresult muUserObjectRetain(MUuserObject object, unsigned int count)

Description

  • Retain a reference to a user object.
  • Retains new references to a user object. The new references are owned by the caller.
  • See MUSA User Objects in the MUSA C++ Programming Guide for more information on user objects.

Parameters

  • object (MUuserObject): The object to retain
  • count (unsigned int): The number of references to retain, typically 1. Must be nonzero and not larger than INT_MAX.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muUserObjectRelease​

MUresult muUserObjectRelease(MUuserObject object, unsigned int count)

Description

  • Release a reference to a user object.
  • Releases user object references owned by the caller. The object's destructor is invoked if the reference count reaches zero.
  • It is undefined behavior to release references not owned by the caller, or to use a user object handle after all references are released.
  • See MUSA User Objects in the MUSA C++ Programming Guide for more information on user objects.

Parameters

  • object (MUuserObject): The object to release
  • count (unsigned int): The number of references to release, typically 1. Must be nonzero and not larger than INT_MAX.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muGraphRetainUserObject​

MUresult muGraphRetainUserObject(MUgraph graph, MUuserObject object, unsigned int count, unsigned int flags)

Description

  • Retain a reference to a user object from a graph.
  • Creates or moves user object references that will be owned by a MUSA graph.
  • See MUSA User Objects in the MUSA C++ Programming Guide for more information on user objects.

Parameters

  • graph (MUgraph): The graph to associate the reference with
  • object (MUuserObject): The user object to retain a reference for
  • count (unsigned int): The number of references to add to the graph, typically 1. Must be nonzero and not larger than INT_MAX.
  • flags (unsigned int): The optional flag MU_GRAPH_USER_OBJECT_MOVE transfers references from the calling thread, rather than create new references. Pass 0 to create new references.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muGraphReleaseUserObject​

MUresult muGraphReleaseUserObject(MUgraph graph, MUuserObject object, unsigned int count)

Description

  • Release a user object reference from a graph.
  • Releases user object references owned by a graph.
  • See MUSA User Objects in the MUSA C++ Programming Guide for more information on user objects.

Parameters

  • graph (MUgraph): The graph that will release the reference
  • object (MUuserObject): The user object to release a reference for
  • count (unsigned int): The number of references to release, typically 1. Must be nonzero and not larger than INT_MAX.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.

See also

muGraphAddMemAtomicNode​

MUresult muGraphAddMemAtomicNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEM_ATOMIC_NODE_PARAMS *memAtomicParams, MUcontext ctx)

Description

  • Creates a memory atomic node and adds it to a graph.
  • Creates a new memory atomic node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will perform the memory atomic operation described by memAtomicParams. See muMemoryAtomicAsync() for a description of the structure.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • memAtomicParams (const MUSA_MEM_ATOMIC_NODE_PARAMS *): Parameters for the memory atomic
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemAtomicValueNode​

MUresult muGraphAddMemAtomicValueNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *memAtomicValueParams, MUcontext ctx)

Description

  • Creates a memory atomic value node and adds it to a graph.
  • Creates a new memory atomic value node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will perform the memory atomic value operation described by memAtomicValueParams. See muMemoryAtomicValueAsync() for a description of the structure.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • memAtomicValueParams (const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *): Parameters for the memory atomic value
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemWaitWriteNode​

MUresult muGraphAddMemWaitWriteNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *memWaitWriteParams, MUcontext ctx)

Description

  • Creates a memory wait / write value node and adds it to a graph.
  • Creates a new memory wait / write value node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will perform the memory wait / write value described by memWaitWriteParams.
typedef struct MUSA_MEM_WAIT_WRITE_NODE_PARAMS_st {
  MUdeviceptr addr;
  muuint64_t value;
  unsigned int flags;
  MUstream BatchMemOpType operation;
} MUSA_MEM_WAIT_WRITE_NODE_PARAMS;
  • See MUstreamBatchMemOpType for the full set of supported operations, and muStreamWaitValue32(), muStreamWaitValue64(), muStreamWriteValue32(), and muStreamWriteValue64() for details of specific operations.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • memWaitWriteParams (const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *): Parameters for the memory atomic value
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddMemTransferNode​

MUresult muGraphAddMemTransferNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, const MUSA_MEM_TRANSFER_NODE_PARAMS *memTransferParams, MUcontext ctx)

Description

  • Creates a memory transfer node and adds it to a graph.
  • Creates a new memory transfer node and adds it to hGraph with numDependencies dependencies specified via dependencies. It is possible for numDependencies to be 0, in which case the node will be placed at the root of the graph. dependencies may not have any duplicate entries. A handle to the new node will be returned in phGraphNode.
  • When the graph is launched, the node will perform the memory transfer described by memTransferParams. See muMemoryTransfer() for a description of the structure and its restrictions.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • memTransferParams (const MUSA_MEM_TRANSFER_NODE_PARAMS *): Parameters for the memory transfer
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemAtomicNodeGetParams​

MUresult muGraphMemAtomicNodeGetParams(MUgraphNode hNode, MUSA_MEM_ATOMIC_NODE_PARAMS *nodeParams)

Description

  • Returns a memory atomic node's parameters.
  • Returns the parameters of memory atomic node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEM_ATOMIC_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemAtomicNodeSetParams​

MUresult muGraphMemAtomicNodeSetParams(MUgraphNode hNode, const MUSA_MEM_ATOMIC_NODE_PARAMS *nodeParams)

Description

  • Sets a memory atomic node's parameters.
  • Sets the parameters of memory atomic node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEM_ATOMIC_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemAtomicValueNodeGetParams​

MUresult muGraphMemAtomicValueNodeGetParams(MUgraphNode hNode, MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *nodeParams)

Description

  • Returns a memory atomic value node's parameters.
  • Returns the parameters of memory atomic value node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemAtomicValueNodeSetParams​

MUresult muGraphMemAtomicValueNodeSetParams(MUgraphNode hNode, const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *nodeParams)

Description

  • Sets a memory atomic value node's parameters.
  • Sets the parameters of memory atomic value node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemWaitWriteNodeGetParams​

MUresult muGraphMemWaitWriteNodeGetParams(MUgraphNode hNode, MUSA_MEM_WAIT_WRITE_NODE_PARAMS *nodeParams)

Description

  • Returns a memory wait / write value node's parameters.
  • Returns the parameters of memory wait / write value node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEM_WAIT_WRITE_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemWaitWriteNodeSetParams​

MUresult muGraphMemWaitWriteNodeSetParams(MUgraphNode hNode, const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *nodeParams)

Description

  • Sets a memory wait / write value node's parameters.
  • Sets the parameters of memory wait / write value node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemTransferNodeGetParams​

MUresult muGraphMemTransferNodeGetParams(MUgraphNode hNode, MUSA_MEM_TRANSFER_NODE_PARAMS *nodeParams)

Description

  • Returns a memory transfer node's parameters.
  • Returns the parameters of memory transfer node hNode in nodeParams.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUSA_MEM_TRANSFER_NODE_PARAMS *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphMemTransferNodeSetParams​

MUresult muGraphMemTransferNodeSetParams(MUgraphNode hNode, const MUSA_MEM_TRANSFER_NODE_PARAMS *nodeParams)

Description

  • Sets a memory transfer node's parameters.
  • Sets the parameters of memory transfer node hNode to nodeParams.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (const MUSA_MEM_TRANSFER_NODE_PARAMS *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemAtomicNodeSetParams​

MUresult muGraphExecMemAtomicNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEM_ATOMIC_NODE_PARAMS *nodeParams, MUcontext ctx)

Description

  • Sets the parameters for a memory atomic node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained nodeParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The source and destination memory in nodeParams must be allocated from the same contexts as the original source and destination memory. Zero-length operations are not supported.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memory atomic node from the graph which was used to instantiate graphExec
  • nodeParams (const MUSA_MEM_ATOMIC_NODE_PARAMS *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemAtomicValueNodeSetParams​

MUresult muGraphExecMemAtomicValueNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *nodeParams, MUcontext ctx)

Description

  • Sets the parameters for a memory atomic value node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained nodeParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The destination memory in nodeParams must be allocated from the same contexts as the original destination memory.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memory atomic value node from the graph which was used to instantiate graphExec
  • nodeParams (const MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemWaitWriteNodeSetParams​

MUresult muGraphExecMemWaitWriteNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *nodeParams, MUcontext ctx)

Description

  • Sets the parameters for a memory wait / write value node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained nodeParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The destination memory in nodeParams must be allocated from the same contexts as the original destination memory.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memory wait / write value node from the graph which was used to instantiate graphExec
  • nodeParams (const MUSA_MEM_WAIT_WRITE_NODE_PARAMS *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecMemTransferNodeSetParams​

MUresult muGraphExecMemTransferNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, const MUSA_MEM_TRANSFER_NODE_PARAMS *nodeParams, MUcontext ctx)

Description

  • Sets the parameters for a memory transfer node in the given graphExec.
  • Updates the work represented by hNode in hGraphExec as though hNode had contained nodeParams at instantiation. hNode must remain in the graph which was used to instantiate hGraphExec. Changed edges to and from hNode are ignored.
  • The source and destination memory in nodeParams must be allocated from the same contexts as the original source and destination memory. Zero-length operations are not supported.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to set the specified node
  • hNode (MUgraphNode): Memory transfer node from the graph which was used to instantiate graphExec
  • nodeParams (const MUSA_MEM_TRANSFER_NODE_PARAMS *): The updated parameters to set
  • ctx (MUcontext): Context on which to run the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddNode​

MUresult muGraphAddNode(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, size_t numDependencies, MUgraphNodeParams *nodeParams)

Description

  • Adds a node of arbitrary type to a graph.
  • Creates a new node in hGraph described by nodeParams with numDependencies dependencies specified via dependencies. numDependencies may be 0. dependencies may be null if numDependencies is 0. dependencies may not have any duplicate entries.
  • nodeParams is a tagged union. The node type should be specified in the type field, and type-specific parameters in the corresponding union member. All unused bytes - that is, reserved0 and all bytes past the utilized union member - must be set to zero. It is recommended to use brace initialization or memset to ensure all bytes are initialized.
  • Note that for some node types, nodeParams may contain "out parameters" which are modified during the call, such as nodeParams->alloc.dptr.
  • A handle to the new node will be returned in phGraphNode.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • numDependencies (size_t): Number of dependencies
  • nodeParams (MUgraphNodeParams *): Specification of the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_NOT_SUPPORTED

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphAddNode_v2​

MUresult muGraphAddNode_v2(MUgraphNode *phGraphNode, MUgraph hGraph, const MUgraphNode *dependencies, const MUgraphEdgeData *dependencyData, size_t numDependencies, MUgraphNodeParams *nodeParams)

Description

  • Adds a node of arbitrary type to a graph (12.3+)
  • Creates a new node in hGraph described by nodeParams with numDependencies dependencies specified via dependencies. numDependencies may be 0. dependencies may be null if numDependencies is 0. dependencies may not have any duplicate entries.
  • nodeParams is a tagged union. The node type should be specified in the type field, and type-specific parameters in the corresponding union member. All unused bytes - that is, reserved0 and all bytes past the utilized union member - must be set to zero. It is recommended to use brace initialization or memset to ensure all bytes are initialized.
  • Note that for some node types, nodeParams may contain "out parameters" which are modified during the call, such as nodeParams->alloc.dptr.
  • A handle to the new node will be returned in phGraphNode.

Parameters

  • phGraphNode (MUgraphNode *): Returns newly created node
  • hGraph (MUgraph): Graph to which to add the node
  • dependencies (const MUgraphNode *): Dependencies of the node
  • dependencyData (const MUgraphEdgeData *): Optional edge data for the dependencies. If NULL, the data is assumed to be default (zeroed) for all dependencies.
  • numDependencies (size_t): Number of dependencies
  • nodeParams (MUgraphNodeParams *): Specification of the node

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_NOT_SUPPORTED

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeSetParams​

MUresult muGraphNodeSetParams(MUgraphNode hNode, MUgraphNodeParams *nodeParams)

Description

  • Update's a graph node's parameters.
  • Sets the parameters of graph node hNode to nodeParams. The node type specified by nodeParams->type must match the type of hNode. nodeParams must be fully initialized and all unused bytes (reserved, padding) zeroed.
  • Modifying parameters is not supported for node types MU_GRAPH_NODE_TYPE_MEM_ALLOC and MU_GRAPH_NODE_TYPE_MEM_FREE.

Parameters

  • hNode (MUgraphNode): Node to set the parameters for
  • nodeParams (MUgraphNodeParams *): Parameters to copy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphNodeGetParams​

MUresult muGraphNodeGetParams(MUgraphNode hNode, MUgraphNodeParams *nodeParams)

Description

  • Return a graph node's parameters.
  • Returns the parameters of graph node hNode in *nodeParams.
  • Any pointers returned in *nodeParams point to driver-owned memory associated with the node. This memory remains valid until the node is destroyed. Any memory pointed to from *nodeParams must not be modified.
  • The returned parameters are a description of the node, but may not be identical to the struct provided at creation and may not be suitable for direct creation of identical nodes. This is because parameters may be partially unspecified and filled in by the driver at creation, may reference non-copyable handles, or may describe ownership semantics or other parameters that govern behavior of node creation but are not part of the final functional descriptor.

Parameters

  • hNode (MUgraphNode): Node to get the parameters for
  • nodeParams (MUgraphNodeParams *): Pointer to return the parameters

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphExecNodeSetParams​

MUresult muGraphExecNodeSetParams(MUgraphExec hGraphExec, MUgraphNode hNode, MUgraphNodeParams *nodeParams)

Description

  • Update's a graph node's parameters in an instantiated graph.
  • Sets the parameters of a node in an executable graph hGraphExec. The node is identified by the corresponding node hNode in the non-executable graph from which the executable graph was instantiated. hNode must not have been removed from the original graph.
  • The modifications only affect future launches of hGraphExec. Already enqueued or running launches of hGraphExec are not affected by this call. hNode is also not modified by this call.
  • Allowed changes to parameters on executable graphs are as follows: Node type Allowed changes kernel See muGraphExecKernelNodeSetParams memcpy Addresses for 1-dimensional copies if allocated in same context; see muGraphExecMemcpyNodeSetParams memset Addresses for 1-dimensional memsets if allocated in same context; see muGraphExecMemsetNodeSetParams host Unrestricted child graph Topology must match and restrictions apply recursively; see muGraphExecUpdate event wait Unrestricted event record Unrestricted external semaphore signal Number of semaphore operations cannot change external semaphore wait Number of semaphore operations cannot change memory allocation API unsupported memory free API unsupported batch memops Addresses, values, and operation type for wait operations; see muGraphExecBatchMemOpNodeSetParams

Parameters

  • hGraphExec (MUgraphExec): The executable graph in which to update the specified node
  • hNode (MUgraphNode): Corresponding node from the graph from which graphExec was instantiated
  • nodeParams (MUgraphNodeParams *): Updated Parameters to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

muGraphConditionalHandleCreate​

MUresult muGraphConditionalHandleCreate(MUgraphConditionalHandle *pHandle_out, MUgraph hGraph, MUcontext ctx, unsigned int defaultLaunchValue, unsigned int flags)

Description

  • Create a conditional handle.
  • Creates a conditional handle associated with hGraph.
  • The conditional handle must be associated with a conditional node in this graph or one of its children.
  • Handles not associated with a conditional node may cause graph instantiation to fail.
  • Handles can only be set from the context with which they are associated.

Parameters

  • pHandle_out (MUgraphConditionalHandle *): Pointer used to return the handle to the caller.
  • hGraph (MUgraph): Graph which will contain the conditional node using this handle.
  • ctx (MUcontext): Context for the handle and associated conditional node.
  • defaultLaunchValue (unsigned int): Optional initial value for the conditional variable. Applied at the beginning of each graph execution if MU_GRAPH_COND_ASSIGN_DEFAULT is set in flags.
  • flags (unsigned int): Currently must be MU_GRAPH_COND_ASSIGN_DEFAULT or 0.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • This function may also return error codes from previous, asynchronous launches.
  • Graph objects are not thread-safe.

See also

3.23 Occupancy​

muOccupancyMaxActiveBlocksPerMultiprocessor​

MUresult muOccupancyMaxActiveBlocksPerMultiprocessor(int *numBlocks, MUfunction func, int blockSize, size_t dynamicSMemSize)

Description

  • Returns occupancy of a function.
  • Returns in *numBlocks the number of the maximum active blocks per streaming multiprocessor.
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will be the current context.

Parameters

  • numBlocks (int *): Returned occupancy
  • func (MUfunction): Kernel for which occupancy is calculated
  • blockSize (int): Block size the kernel is intended to be launched with
  • dynamicSMemSize (size_t): Per-block dynamic shared memory usage intended, in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • musaOccupancyMaxActiveBlocksPerMultiprocessor

muOccupancyMaxActiveBlocksPerMultiprocessorWithFlags​

MUresult muOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(int *numBlocks, MUfunction func, int blockSize, size_t dynamicSMemSize, unsigned int flags)

Description

  • Returns occupancy of a function.
  • Returns in *numBlocks the number of the maximum active blocks per streaming multiprocessor.
  • The Flags parameter controls how special cases are handled. The valid flags are:
  • MU_OCCUPANCY_DEFAULT, which maintains the default behavior as muOccupancyMaxActiveBlocksPerMultiprocessor; MU_OCCUPANCY_DISABLE_CACHING_OVERRIDE, which suppresses the default behavior on platform where global caching affects occupancy. On such platforms, if caching is enabled, but per-block SM resource usage would result in zero occupancy, the occupancy calculator will calculate the occupancy as if caching is disabled. Setting MU_OCCUPANCY_DISABLE_CACHING_OVERRIDE makes the occupancy calculator to return 0 in such cases. More information can be found about this feature in the "Unified L1/Texture Cache" section of the Maxwell tuning guide.
  • Note that the API can also be with launch context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will be the current context.

Parameters

  • numBlocks (int *): Returned occupancy
  • func (MUfunction): Kernel for which occupancy is calculated
  • blockSize (int): Block size the kernel is intended to be launched with
  • dynamicSMemSize (size_t): Per-block dynamic shared memory usage intended, in bytes
  • flags (unsigned int): Requested behavior for the occupancy calculator

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muOccupancyMaxPotentialBlockSize​

MUresult muOccupancyMaxPotentialBlockSize(int *minGridSize, int *blockSize, MUfunction func, MUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit)

Description

  • Suggest a launch configuration with reasonable occupancy.
  • Returns in *blockSize a reasonable block size that can achieve the maximum occupancy (or, the maximum number of active warps with the fewest blocks per multiprocessor), and in *minGridSize the minimum grid size to achieve the maximum occupancy.
  • If blockSizeLimit is 0, the configurator will use the maximum block size permitted by the device / function instead.
  • If per-block dynamic shared memory allocation is not needed, the user should leave both blockSizeToDynamicSMemSize and dynamicSMemSize as 0.
  • If per-block dynamic shared memory allocation is needed, then if the dynamic shared memory size is constant regardless of block size, the size should be passed through dynamicSMemSize, and blockSizeToDynamicSMemSize should be NULL.
  • Otherwise, if the per-block dynamic shared memory size varies with different block sizes, the user needs to provide a unary function through blockSizeToDynamicSMemSize that computes the dynamic shared memory needed by func for any given block size. dynamicSMemSize is ignored. An example signature is:
  • //Takeblocksize,returnsdynamicsharedmemoryneeded size_tblockToSmem(intblockSize);
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will be the current context.

Parameters

  • minGridSize (int *): Returned minimum grid size needed to achieve the maximum occupancy
  • blockSize (int *): Returned maximum block size that can achieve the maximum occupancy
  • func (MUfunction): Kernel for which launch configuration is calculated
  • blockSizeToDynamicSMemSize (MUoccupancyB2DSize): A function that calculates how much per-block dynamic shared memory func uses based on the block size
  • dynamicSMemSize (size_t): Dynamic shared memory usage intended, in bytes
  • blockSizeLimit (int): The maximum block size func is designed to handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • musaOccupancyMaxPotentialBlockSize

muOccupancyMaxPotentialBlockSizeWithFlags​

MUresult muOccupancyMaxPotentialBlockSizeWithFlags(int *minGridSize, int *blockSize, MUfunction func, MUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit, unsigned int flags)

Description

  • Suggest a launch configuration with reasonable occupancy.
  • An extended version of muOccupancyMaxPotentialBlockSize. In addition to arguments passed to muOccupancyMaxPotentialBlockSize, muOccupancyMaxPotentialBlockSizeWithFlags also takes a Flags parameter.
  • The Flags parameter controls how special cases are handled. The valid flags are:
  • MU_OCCUPANCY_DEFAULT, which maintains the default behavior as muOccupancyMaxPotentialBlockSize; MU_OCCUPANCY_DISABLE_CACHING_OVERRIDE, which suppresses the default behavior on platform where global caching affects occupancy. On such platforms, the launch configurations that produces maximal occupancy might not support global caching. Setting MU_OCCUPANCY_DISABLE_CACHING_OVERRIDE guarantees that the the produced launch configuration is global caching compatible at a potential cost of occupancy. More information can be found about this feature in the "Unified L1/Texture Cache" section of the Maxwell tuning guide.
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will be the current context.

Parameters

  • minGridSize (int *): Returned minimum grid size needed to achieve the maximum occupancy
  • blockSize (int *): Returned maximum block size that can achieve the maximum occupancy
  • func (MUfunction): Kernel for which launch configuration is calculated
  • blockSizeToDynamicSMemSize (MUoccupancyB2DSize): A function that calculates how much per-block dynamic shared memory func uses based on the block size
  • dynamicSMemSize (size_t): Dynamic shared memory usage intended, in bytes
  • blockSizeLimit (int): The maximum block size func is designed to handle
  • flags (unsigned int): Options

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

  • musaOccupancyMaxPotentialBlockSizeWithFlags

muOccupancyAvailableDynamicSMemPerBlock​

MUresult muOccupancyAvailableDynamicSMemPerBlock(size_t *dynamicSmemSize, MUfunction func, int numBlocks, int blockSize)

Description

  • Returns dynamic shared memory available per block when launching numBlocks blocks on SM.
  • Returns in *dynamicSmemSize the maximum size of dynamic shared memory to allow numBlocks blocks per SM.
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will be the current context.

Parameters

  • dynamicSmemSize (size_t *): Returned maximum dynamic shared memory
  • func (MUfunction): Kernel function for which occupancy is calculated
  • numBlocks (int): Number of blocks to fit on SM
  • blockSize (int): Size of the blocks

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

muOccupancyMaxPotentialClusterSize​

MUresult muOccupancyMaxPotentialClusterSize(int *clusterSize, MUfunction func, const MUlaunchConfig *config)

Description

  • Given the kernel function (func) and launch configuration (config), return the maximum cluster size in *clusterSize.
  • The cluster dimensions in config are ignored. If func has a required cluster size set (see musaFuncGetAttributes / muFuncGetAttribute),*clusterSize will reflect the required cluster size.
  • By default this function will always return a value that's portable on future hardware. A higher value may be returned if the kernel function allows non-portable cluster sizes.
  • This function will respect the compile time launch bounds.
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will either be taken from the specified stream config->hStream or the current context in case of NULL stream.

Parameters

  • clusterSize (int *): Returned maximum cluster size that can be launched for the given kernel function and launch configuration
  • func (MUfunction): Kernel function for which maximum cluster size is calculated
  • config (const MUlaunchConfig *): Launch configuration for the given kernel function

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muOccupancyMaxActiveClusters​

MUresult muOccupancyMaxActiveClusters(int *numClusters, MUfunction func, const MUlaunchConfig *config)

Description

  • Given the kernel function (func) and launch configuration (config), return the maximum number of clusters that could co-exist on the target device in *numClusters.
  • If the function has required cluster size already set (see musaFuncGetAttributes / muFuncGetAttribute), the cluster size from config must either be unspecified or match the required size. Without required sizes, the cluster size must be specified in config, else the function will return an error.
  • Note that various attributes of the kernel function may affect occupancy calculation. Runtime environment may affect how the hardware schedules the clusters, so the calculated occupancy is not guaranteed to be achievable.
  • Note that the API can also be used with context-less kernel MUkernel by querying the handle using muLibraryGetKernel() and then passing it to the API by casting to MUfunction. Here, the context to use for calculations will either be taken from the specified stream config->hStream or the current context in case of NULL stream.

Parameters

  • numClusters (int *): Returned maximum number of clusters that could co-exist on the target device
  • func (MUfunction): Kernel function for which maximum number of clusters are calculated
  • config (const MUlaunchConfig *): Launch configuration for the given kernel function

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_CLUSTER_SIZE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.24 Texture Reference Management [DEPRECATED]​

muTexRefSetArray​

MUresult muTexRefSetArray(MUtexref hTexRef, MUarray hArray, unsigned int Flags)

Description

  • Binds an array as a texture reference.
  • Deprecated
  • Binds the MUSA array hArray to the texture reference hTexRef. Any previous address or MUSA array state associated with the texture reference is superseded by this function. Flags must be set to MU_TRSA_OVERRIDE_FORMAT. Any MUSA array previously bound to hTexRef is unbound.

Parameters

  • hTexRef (MUtexref): Texture reference to bind
  • hArray (MUarray): Array to bind
  • Flags (unsigned int): Options (must be MU_TRSA_OVERRIDE_FORMAT)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetMipmappedArray​

MUresult muTexRefSetMipmappedArray(MUtexref hTexRef, MUmipmappedArray hMipmappedArray, unsigned int Flags)

Description

  • Binds a mipmapped array to a texture reference.
  • Deprecated
  • Binds the MUSA mipmapped array hMipmappedArray to the texture reference hTexRef. Any previous address or MUSA array state associated with the texture reference is superseded by this function. Flags must be set to MU_TRSA_OVERRIDE_FORMAT. Any MUSA array previously bound to hTexRef is unbound.

Parameters

  • hTexRef (MUtexref): Texture reference to bind
  • hMipmappedArray (MUmipmappedArray): Mipmapped array to bind
  • Flags (unsigned int): Options (must be MU_TRSA_OVERRIDE_FORMAT)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetAddress​

MUresult muTexRefSetAddress(size_t *ByteOffset, MUtexref hTexRef, MUdeviceptr dptr, size_t bytes)

Description

  • Binds an address as a texture reference.
  • Deprecated
  • Binds a linear address range to the texture reference hTexRef. Any previous address or MUSA array state associated with the texture reference is superseded by this function. Any memory previously bound to hTexRef is unbound.
  • Since the hardware enforces an alignment requirement on texture base addresses, muTexRefSetAddress() passes back a byte offset in *ByteOffset that must be applied to texture fetches in order to read from the desired memory. This offset must be divided by the texel size and passed to kernels that read from the texture so they can be applied to the tex1Dfetch() function.
  • If the device memory pointer was returned from muMemAlloc(), the offset is guaranteed to be 0 and NULL may be passed as the ByteOffset parameter.
  • The total number of elements (or texels) in the linear address range cannot exceed MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_LINEAR_WIDTH. The number of elements is computed as (bytes / bytesPerElement), where bytesPerElement is determined from the data format and number of components set using muTexRefSetFormat().

Parameters

  • ByteOffset (size_t *): Returned byte offset
  • hTexRef (MUtexref): Texture reference to bind
  • dptr (MUdeviceptr): Device pointer to bind
  • bytes (size_t): Size of memory to bind in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muTexRefSetAddress_v2.

See also

muTexRefSetAddress2D​

MUresult muTexRefSetAddress2D(MUtexref hTexRef, const MUSA_ARRAY_DESCRIPTOR *desc, MUdeviceptr dptr, size_t Pitch)

Description

  • Binds an address as a 2D texture reference.
  • Deprecated
  • Binds a linear address range to the texture reference hTexRef. Any previous address or MUSA array state associated with the texture reference is superseded by this function. Any memory previously bound to hTexRef is unbound.
  • Using a tex2D() function inside a kernel requires a call to either muTexRefSetArray() to bind the corresponding texture reference to an array, or muTexRefSetAddress2D() to bind the texture reference to linear memory.
  • Function calls to muTexRefSetFormat() cannot follow calls to muTexRefSetAddress2D() for the same texture reference.
  • It is required that dptr be aligned to the appropriate hardware-specific texture alignment. You can query this value using the device attribute MU_DEVICE_ATTRIBUTE_TEXTURE_ALIGNMENT. If an unaligned dptr is supplied, MUSA_ERROR_INVALID_VALUE is returned.
  • Pitch has to be aligned to the hardware-specific texture pitch alignment. This value can be queried using the device attribute MU_DEVICE_ATTRIBUTE_TEXTURE_PITCH_ALIGNMENT. If an unaligned Pitch is supplied, MUSA_ERROR_INVALID_VALUE is returned.
  • Width and Height, which are specified in elements (or texels), cannot exceed MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_WIDTH and MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_HEIGHT respectively. Pitch, which is specified in bytes, cannot exceed MU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_PITCH.

Parameters

  • hTexRef (MUtexref): Texture reference to bind
  • desc (const MUSA_ARRAY_DESCRIPTOR *): Descriptor of MUSA array
  • dptr (MUdeviceptr): Device pointer to bind
  • Pitch (size_t): Line pitch in bytes

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muTexRefSetAddress2D_v3.

See also

muTexRefSetFormat​

MUresult muTexRefSetFormat(MUtexref hTexRef, MUarray_format fmt, int NumPackedComponents)

Description

  • Sets the format for a texture reference.
  • Deprecated
  • Specifies the format of the data to be read by the texture reference hTexRef. fmt and NumPackedComponents are exactly analogous to the Format and NumChannels members of the MUSA_ARRAY_DESCRIPTOR structure: They specify the format of each component and the number of components per array element.

Parameters

  • hTexRef (MUtexref): Texture reference
  • fmt (MUarray_format): Format to set
  • NumPackedComponents (int): Number of components per array element

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetAddressMode​

MUresult muTexRefSetAddressMode(MUtexref hTexRef, int dim, MUaddress_mode am)

Description

  • Sets the addressing mode for a texture reference.
  • Deprecated
  • Specifies the addressing mode am for the given dimension dim of the texture reference hTexRef. If dim is zero, the addressing mode is applied to the first parameter of the functions used to fetch from the texture; if dim is 1, the second, and so on. MUaddress_mode is defined as:
typedef enum MUaddress_mode_enum {
  MU_TR_ADDRESS_MODE_WRAP = 0,
  MU_TR_ADDRESS_MODE_CLAMP = 1,
  MU_TR_ADDRESS_MODE_MIRROR = 2,
  MU_TR_ADDRESS_MODE_BORDER = 3;
} MUaddress_mode;
  • Note that this call has no effect if hTexRef is bound to linear memory. Also, if the flag, MU_TRSF_NORMALIZED_COORDINATES, is not set, the only supported address mode is MU_TR_ADDRESS_MODE_CLAMP.

Parameters

  • hTexRef (MUtexref): Texture reference
  • dim (int): Dimension
  • am (MUaddress_mode): Addressing mode to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetFilterMode​

MUresult muTexRefSetFilterMode(MUtexref hTexRef, MUfilter_mode fm)

Description

  • Sets the filtering mode for a texture reference.
  • Deprecated
  • Specifies the filtering mode fm to be used when reading memory through the texture reference hTexRef. MUfilter_mode_enum is defined as:
typedef enum MUfilter_mode_enum {
  MU_TR_FILTER_MODE_POINT = 0,
  MU_TR_FILTER_MODE_LINEAR = 1;
} MUfilter_mode;
  • Note that this call has no effect if hTexRef is bound to linear memory.

Parameters

  • hTexRef (MUtexref): Texture reference
  • fm (MUfilter_mode): Filtering mode to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetMipmapFilterMode​

MUresult muTexRefSetMipmapFilterMode(MUtexref hTexRef, MUfilter_mode fm)

Description

  • Sets the mipmap filtering mode for a texture reference.
  • Deprecated
  • Specifies the mipmap filtering mode fm to be used when reading memory through the texture reference hTexRef. MUfilter_mode_enum is defined as:
typedef enum MUfilter_mode_enum {
  MU_TR_FILTER_MODE_POINT = 0,
  MU_TR_FILTER_MODE_LINEAR = 1;
} MUfilter_mode;
  • Note that this call has no effect if hTexRef is not bound to a mipmapped array.

Parameters

  • hTexRef (MUtexref): Texture reference
  • fm (MUfilter_mode): Filtering mode to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetMipmapLevelBias​

MUresult muTexRefSetMipmapLevelBias(MUtexref hTexRef, float bias)

Description

  • Sets the mipmap level bias for a texture reference.
  • Deprecated
  • Specifies the mipmap level bias bias to be added to the specified mipmap level when reading memory through the texture reference hTexRef.
  • Note that this call has no effect if hTexRef is not bound to a mipmapped array.

Parameters

  • hTexRef (MUtexref): Texture reference
  • bias (float): Mipmap level bias

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetMipmapLevelClamp​

MUresult muTexRefSetMipmapLevelClamp(MUtexref hTexRef, float minMipmapLevelClamp, float maxMipmapLevelClamp)

Description

  • Sets the mipmap min/max mipmap level clamps for a texture reference.
  • Deprecated
  • Specifies the min/max mipmap level clamps, minMipmapLevelClamp and maxMipmapLevelClamp respectively, to be used when reading memory through the texture reference hTexRef.
  • Note that this call has no effect if hTexRef is not bound to a mipmapped array.

Parameters

  • hTexRef (MUtexref): Texture reference
  • minMipmapLevelClamp (float): Mipmap min level clamp
  • maxMipmapLevelClamp (float): Mipmap max level clamp

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetMaxAnisotropy​

MUresult muTexRefSetMaxAnisotropy(MUtexref hTexRef, unsigned int maxAniso)

Description

  • Sets the maximum anisotropy for a texture reference.
  • Deprecated
  • Specifies the maximum anisotropy maxAniso to be used when reading memory through the texture reference hTexRef.
  • Note that this call has no effect if hTexRef is bound to linear memory.

Parameters

  • hTexRef (MUtexref): Texture reference
  • maxAniso (unsigned int): Maximum anisotropy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetBorderColor​

MUresult muTexRefSetBorderColor(MUtexref hTexRef, float *pBorderColor)

Description

  • Sets the border color for a texture reference.
  • Deprecated
  • Specifies the value of the RGBA color via the pBorderColor to the texture reference hTexRef. The color value supports only float type and holds color components in the following sequence: pBorderColor[0] holds 'R' component pBorderColor[1] holds 'G' component pBorderColor[2] holds 'B' component pBorderColor[3] holds 'A' component
  • Note that the color values can be set only when the Address mode is set to MU_TR_ADDRESS_MODE_BORDER using muTexRefSetAddressMode. Applications using integer border color values have to "reinterpret_cast" their values to float.

Parameters

  • hTexRef (MUtexref): Texture reference
  • pBorderColor (float *): RGBA color

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefSetFlags​

MUresult muTexRefSetFlags(MUtexref hTexRef, unsigned int Flags)

Description

  • Sets the flags for a texture reference.
  • Deprecated
  • Specifies optional flags via Flags to specify the behavior of data returned through the texture reference hTexRef. The valid flags are:
  • MU_TRSF_READ_AS_INTEGER, which suppresses the default behavior of having the texture promote integer data to floating point data in the range [0, 1]. Note that texture with 32-bit integer format would not be promoted, regardless of whether or not this flag is specified; MU_TRSF_NORMALIZED_COORDINATES, which suppresses the default behavior of having the texture coordinates range from [0, Dim) where Dim is the width or height of the MUSA array. Instead, the texture coordinates [0, 1.0) reference the entire breadth of the array dimension; MU_TRSF_DISABLE_TRILINEAR_OPTIMIZATION, which disables any trilinear filtering optimizations. Trilinear optimizations improve texture filtering performance by allowing bilinear filtering on textures in scenarios where it can closely approximate the expected results.

Parameters

  • hTexRef (MUtexref): Texture reference
  • Flags (unsigned int): Optional flags to set

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetAddress​

MUresult muTexRefGetAddress(MUdeviceptr *pdptr, MUtexref hTexRef)

Description

  • Gets the address associated with a texture reference.
  • Deprecated
  • Returns in *pdptr the base address bound to the texture reference hTexRef, or returns MUSA_ERROR_INVALID_VALUE if the texture reference is not bound to any device memory range.

Parameters

  • pdptr (MUdeviceptr *): Returned device address
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

Note

  • Additional exported symbol names in scope: muTexRefGetAddress_v2.

See also

muTexRefGetArray​

MUresult muTexRefGetArray(MUarray *phArray, MUtexref hTexRef)

Description

  • Gets the array bound to a texture reference.
  • Deprecated
  • Returns in *phArray the MUSA array bound to the texture reference hTexRef, or returns MUSA_ERROR_INVALID_VALUE if the texture reference is not bound to any MUSA array.

Parameters

  • phArray (MUarray *): Returned array
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetMipmappedArray​

MUresult muTexRefGetMipmappedArray(MUmipmappedArray *phMipmappedArray, MUtexref hTexRef)

Description

  • Gets the mipmapped array bound to a texture reference.
  • Deprecated
  • Returns in *phMipmappedArray the MUSA mipmapped array bound to the texture reference hTexRef, or returns MUSA_ERROR_INVALID_VALUE if the texture reference is not bound to any MUSA mipmapped array.

Parameters

  • phMipmappedArray (MUmipmappedArray *): Returned mipmapped array
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetAddressMode​

MUresult muTexRefGetAddressMode(MUaddress_mode *pam, MUtexref hTexRef, int dim)

Description

  • Gets the addressing mode used by a texture reference.
  • Deprecated
  • Returns in *pam the addressing mode corresponding to the dimension dim of the texture reference hTexRef. Currently, the only valid value for dim are 0 and 1.

Parameters

  • pam (MUaddress_mode *): Returned addressing mode
  • hTexRef (MUtexref): Texture reference
  • dim (int): Dimension

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetFilterMode​

MUresult muTexRefGetFilterMode(MUfilter_mode *pfm, MUtexref hTexRef)

Description

  • Gets the filter-mode used by a texture reference.
  • Deprecated
  • Returns in *pfm the filtering mode of the texture reference hTexRef.

Parameters

  • pfm (MUfilter_mode *): Returned filtering mode
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetFormat​

MUresult muTexRefGetFormat(MUarray_format *pFormat, int *pNumChannels, MUtexref hTexRef)

Description

  • Gets the format used by a texture reference.
  • Deprecated
  • Returns in *pFormat and *pNumChannels the format and number of components of the MUSA array bound to the texture reference hTexRef. If pFormat or pNumChannels is NULL, it will be ignored.

Parameters

  • pFormat (MUarray_format *): Returned format
  • pNumChannels (int *): Returned number of components
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetMipmapFilterMode​

MUresult muTexRefGetMipmapFilterMode(MUfilter_mode *pfm, MUtexref hTexRef)

Description

  • Gets the mipmap filtering mode for a texture reference.
  • Deprecated
  • Returns the mipmap filtering mode in pfm that's used when reading memory through the texture reference hTexRef.

Parameters

  • pfm (MUfilter_mode *): Returned mipmap filtering mode
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetMipmapLevelBias​

MUresult muTexRefGetMipmapLevelBias(float *pbias, MUtexref hTexRef)

Description

  • Gets the mipmap level bias for a texture reference.
  • Deprecated
  • Returns the mipmap level bias in pBias that's added to the specified mipmap level when reading memory through the texture reference hTexRef.

Parameters

  • pbias (float *): Returned mipmap level bias
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetMipmapLevelClamp​

MUresult muTexRefGetMipmapLevelClamp(float *pminMipmapLevelClamp, float *pmaxMipmapLevelClamp, MUtexref hTexRef)

Description

  • Gets the min/max mipmap level clamps for a texture reference.
  • Deprecated
  • Returns the min/max mipmap level clamps in pminMipmapLevelClamp and pmaxMipmapLevelClamp that's used when reading memory through the texture reference hTexRef.

Parameters

  • pminMipmapLevelClamp (float *): Returned mipmap min level clamp
  • pmaxMipmapLevelClamp (float *): Returned mipmap max level clamp
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetMaxAnisotropy​

MUresult muTexRefGetMaxAnisotropy(int *pmaxAniso, MUtexref hTexRef)

Description

  • Gets the maximum anisotropy for a texture reference.
  • Deprecated
  • Returns the maximum anisotropy in pmaxAniso that's used when reading memory through the texture reference hTexRef.

Parameters

  • pmaxAniso (int *): Returned maximum anisotropy
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetBorderColor​

MUresult muTexRefGetBorderColor(float *pBorderColor, MUtexref hTexRef)

Description

  • Gets the border color used by a texture reference.
  • Deprecated
  • Returns in pBorderColor, values of the RGBA color used by the texture reference hTexRef. The color value is of type float and holds color components in the following sequence: pBorderColor[0] holds 'R' component pBorderColor[1] holds 'G' component pBorderColor[2] holds 'B' component pBorderColor[3] holds 'A' component

Parameters

  • pBorderColor (float *): Returned Type and Value of RGBA color
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefGetFlags​

MUresult muTexRefGetFlags(unsigned int *pFlags, MUtexref hTexRef)

Description

  • Gets the flags used by a texture reference.
  • Deprecated
  • Returns in *pFlags the flags of the texture reference hTexRef.

Parameters

  • pFlags (unsigned int *): Returned flags
  • hTexRef (MUtexref): Texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefCreate​

MUresult muTexRefCreate(MUtexref *pTexRef)

Description

  • Creates a texture reference.
  • Deprecated
  • Creates a texture reference and returns its handle in *pTexRef. Once created, the application must call muTexRefSetArray() or muTexRefSetAddress() to associate the reference with allocated memory. Other texture reference functions are used to specify the format and interpretation (addressing, filtering, etc.) to be used when the memory is read through this texture reference.

Parameters

  • pTexRef (MUtexref *): Returned texture reference

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexRefDestroy​

MUresult muTexRefDestroy(MUtexref hTexRef)

Description

  • Destroys a texture reference.
  • Deprecated
  • Destroys the texture reference specified by hTexRef.

Parameters

  • hTexRef (MUtexref): Texture reference to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

3.25 Surface Reference Management [DEPRECATED]​

muSurfRefSetArray​

MUresult muSurfRefSetArray(MUsurfref hSurfRef, MUarray hArray, unsigned int Flags)

Description

  • Sets the MUSA array for a surface reference.
  • Deprecated
  • Sets the MUSA array hArray to be read and written by the surface reference hSurfRef. Any previous MUSA array state associated with the surface reference is superseded by this function. Flags must be set to 0. The MUSA_ARRAY3D_SURFACE_LDST flag must have been set for the MUSA array. Any MUSA array previously bound to hSurfRef is unbound.

Parameters

  • hSurfRef (MUsurfref): Surface reference handle
  • hArray (MUarray): MUSA array handle
  • Flags (unsigned int): set to 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muSurfRefGetArray​

MUresult muSurfRefGetArray(MUarray *phArray, MUsurfref hSurfRef)

Description

  • Passes back the MUSA array bound to a surface reference.
  • Deprecated
  • Returns in *phArray the MUSA array bound to the surface reference hSurfRef, or returns MUSA_ERROR_INVALID_VALUE if the surface reference is not bound to any MUSA array.

Parameters

  • phArray (MUarray *): Surface reference handle
  • hSurfRef (MUsurfref): Surface reference handle

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

3.26 Texture Object Management​

muTexObjectCreate​

MUresult muTexObjectCreate(MUtexObject *pTexObject, const MUSA_RESOURCE_DESC *pResDesc, const MUSA_TEXTURE_DESC *pTexDesc, const MUSA_RESOURCE_VIEW_DESC *pResViewDesc)

Description

  • Creates a texture object.
  • Creates a texture object and returns it in pTexObject. pResDesc describes the data to texture from. pTexDesc describes how the data should be sampled. pResViewDesc is an optional argument that specifies an alternate format for the data described by pResDesc, and also describes the subresource region to restrict access to when texturing. pResViewDesc can only be specified if the type of resource is a MUSA array or a MUSA mipmapped array not in a block compressed format.
  • Texture objects are only supported on devices of compute capability 3.0 or higher. Additionally, a texture object is an opaque value, and, as such, should only be accessed through MUSA API calls.
  • The MUSA_RESOURCE_DESC structure is defined as:
typedef struct MUSA_RESOURCE_DESC_st  {
  MUresourcetype resType;
  union {
    struct {
      MUarray hArray;
    } array;
    struct {
      MUmipmappedArray hMipmappedArray;
    } mipmap;
    struct {
      MUdeviceptr devPtr;
      MUarray_format format;
      unsigned int numChannels;
      size_t sizeInBytes;
    } linear;
    struct {
      MUdeviceptr devPtr;
      MUarray_format format;
      unsigned int numChannels;
      size_t width;
      size_t height;
      size_t pitchInBytes;
    } pitch2D;
  } res;
  unsigned int flags;
} MUSA_RESOURCE_DESC;
  • where: MUSA_RESOURCE_DESC::resType specifies the type of resource to texture from. MUresourceType is defined as:
typedef enum MUresourcetype_enum {
  MU_RESOURCE_TYPE_ARRAY = 0x00,
  MU_RESOURCE_TYPE_MIPMAPPED_ARRAY = 0x01,
  MU_RESOURCE_TYPE_LINEAR = 0x02,
  MU_RESOURCE_TYPE_PITCH2D = 0x03;
} MUresourcetype;
  • The MUSA_TEXTURE_DESC struct is defined as
typedef struct MUSA_TEXTURE_DESC_st {
  MUaddress_mode addressMode[3];
  MUfilter_mode filterMode;
  unsigned int flags;
  unsigned int maxAnisotropy;
  MUfilter_mode mipmapFilterMode;
  float mipmapLevelBias;
  float minMipmapLevelClamp;
  float maxMipmapLevelClamp;
} MUSA_TEXTURE_DESC;
  • where MUSA_TEXTURE_DESC::addressMode specifies the addressing mode for each dimension of the texture data. MUaddress_mode is defined as:
typedef enum MUaddress_mode_enum {
  MU_TR_ADDRESS_MODE_WRAP = 0,
  MU_TR_ADDRESS_MODE_CLAMP = 1,
  MU_TR_ADDRESS_MODE_MIRROR = 2,
  MU_TR_ADDRESS_MODE_BORDER = 3;
} MUaddress_mode;
  • This is ignored if MUSA_RESOURCE_DESC::resType is MU_RESOURCE_TYPE_LINEAR. Also, if the flag, MU_TRSF_NORMALIZED_COORDINATES is not set, the only supported address mode is MU_TR_ADDRESS_MODE_CLAMP. MUSA_TEXTURE_DESC::filterMode specifies the filtering mode to be used when fetching from the texture. MUfilter_mode is defined as:
typedef enum MUfilter_mode_enum {
  MU_TR_FILTER_MODE_POINT = 0,
  MU_TR_FILTER_MODE_LINEAR = 1;
} MUfilter_mode;
  • This is ignored if MUSA_RESOURCE_DESC::resType is MU_RESOURCE_TYPE_LINEAR. MUSA_TEXTURE_DESC::flags can be any combination of the following: MU_TRSF_READ_AS_INTEGER, which suppresses the default behavior of having the texture promote integer data to floating point data in the range [0, 1]. Note that texture with 32-bit integer format would not be promoted, regardless of whether or not this flag is specified. MU_TRSF_NORMALIZED_COORDINATES, which suppresses the default behavior of having the texture coordinates range from [0, Dim) where Dim is the width or height of the MUSA array. Instead, the texture coordinates [0, 1.0) reference the entire breadth of the array dimension; Note that for MUSA mipmapped arrays, this flag has to be set. MU_TRSF_DISABLE_TRILINEAR_OPTIMIZATION, which disables any trilinear filtering optimizations. Trilinear optimizations improve texture filtering performance by allowing bilinear filtering on textures in scenarios where it can closely approximate the expected results. MU_TRSF_SEAMLESS_CUBEMAP, which enables seamless cube map filtering. This flag can only be specified if the underlying resource is a MUSA array or a MUSA mipmapped array that was created with the flag MUSA_ARRAY3D_CUBEMAP. When seamless cube map filtering is enabled, texture address modes specified by MUSA_TEXTURE_DESC::addressMode are ignored. Instead, if the MUSA_TEXTURE_DESC::filterMode is set to MU_TR_FILTER_MODE_POINT the address mode MU_TR_ADDRESS_MODE_CLAMP will be applied for all dimensions. If the MUSA_TEXTURE_DESC::filterMode is set to MU_TR_FILTER_MODE_LINEAR seamless cube map filtering will be performed when sampling along the cube face borders. MUSA_TEXTURE_DESC::maxAnisotropy specifies the maximum anisotropy ratio to be used when doing anisotropic filtering. This value will be clamped to the range [1,16]. MUSA_TEXTURE_DESC::mipmapFilterMode specifies the filter mode when the calculated mipmap level lies between two defined mipmap levels. MUSA_TEXTURE_DESC::mipmapLevelBias specifies the offset to be applied to the calculated mipmap level. MUSA_TEXTURE_DESC::minMipmapLevelClamp specifies the lower end of the mipmap level range to clamp access to. MUSA_TEXTURE_DESC::maxMipmapLevelClamp specifies the upper end of the mipmap level range to clamp access to.
  • The MUSA_RESOURCE_VIEW_DESC struct is defined as
typedef struct MUSA_RESOURCE_VIEW_DESC_st  {
  MUresourceViewFormat format;
  size_t width;
  size_t height;
  size_t depth;
  unsigned int firstMipmapLevel;
  unsigned int lastMipmapLevel;
  unsigned int firstLayer;
  unsigned int lastLayer;
} MUSA_RESOURCE_VIEW_DESC;
  • where: MUSA_RESOURCE_VIEW_DESC::format specifies how the data contained in the MUSA array or MUSA mipmapped array should be interpreted. Note that this can incur a change in size of the texture data. If the resource view format is a block compressed format, then the underlying MUSA array or MUSA mipmapped array has to have a base of format MU_AD_FORMAT_UNSIGNED_INT32. with 2 or 4 channels, depending on the block compressed format. For ex., BC1 and BC4 require the underlying MUSA array to have a format of MU_AD_FORMAT_UNSIGNED_INT32 with 2 channels. The other BC formats require the underlying resource to have the same base format but with 4 channels. MUSA_RESOURCE_VIEW_DESC::width specifies the new width of the texture data. If the resource view format is a block compressed format, this value has to be 4 times the original width of the resource. For non block compressed formats, this value has to be equal to that of the original resource. MUSA_RESOURCE_VIEW_DESC::height specifies the new height of the texture data. If the resource view format is a block compressed format, this value has to be 4 times the original height of the resource. For non block compressed formats, this value has to be equal to that of the original resource. MUSA_RESOURCE_VIEW_DESC::depth specifies the new depth of the texture data. This value has to be equal to that of the original resource. MUSA_RESOURCE_VIEW_DESC::firstMipmapLevel specifies the most detailed mipmap level. This will be the new mipmap level zero. For non-mipmapped resources, this value has to be zero.MUSA_TEXTURE_DESC::minMipmapLevelClamp and MUSA_TEXTURE_DESC::maxMipmapLevelClamp will be relative to this value. For ex., if the firstMipmapLevel is set to 2, and a minMipmapLevelClamp of 1.2 is specified, then the actual minimum mipmap level clamp will be 3.2. MUSA_RESOURCE_VIEW_DESC::lastMipmapLevel specifies the least detailed mipmap level. For non-mipmapped resources, this value has to be zero. MUSA_RESOURCE_VIEW_DESC::firstLayer specifies the first layer index for layered textures. This will be the new layer zero. For non-layered resources, this value has to be zero. MUSA_RESOURCE_VIEW_DESC::lastLayer specifies the last layer index for layered textures. For non-layered resources, this value has to be zero.

Parameters

  • pTexObject (MUtexObject *): Texture object to create
  • pResDesc (const MUSA_RESOURCE_DESC *): Resource descriptor
  • pTexDesc (const MUSA_TEXTURE_DESC *): Texture descriptor
  • pResViewDesc (const MUSA_RESOURCE_VIEW_DESC *): Resource view descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexObjectDestroy​

MUresult muTexObjectDestroy(MUtexObject texObject)

Description

  • Destroys a texture object.
  • Destroys the texture object specified by texObject.

Parameters

  • texObject (MUtexObject): Texture object to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexObjectGetResourceDesc​

MUresult muTexObjectGetResourceDesc(MUSA_RESOURCE_DESC *pResDesc, MUtexObject texObject)

Description

  • Returns a texture object's resource descriptor.
  • Returns the resource descriptor for the texture object specified by texObject.

Parameters

  • pResDesc (MUSA_RESOURCE_DESC *): Resource descriptor
  • texObject (MUtexObject): Texture object

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexObjectGetTextureDesc​

MUresult muTexObjectGetTextureDesc(MUSA_TEXTURE_DESC *pTexDesc, MUtexObject texObject)

Description

  • Returns a texture object's texture descriptor.
  • Returns the texture descriptor for the texture object specified by texObject.

Parameters

  • pTexDesc (MUSA_TEXTURE_DESC *): Texture descriptor
  • texObject (MUtexObject): Texture object

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muTexObjectGetResourceViewDesc​

MUresult muTexObjectGetResourceViewDesc(MUSA_RESOURCE_VIEW_DESC *pResViewDesc, MUtexObject texObject)

Description

  • Returns a texture object's resource view descriptor.
  • Returns the resource view descriptor for the texture object specified by texObject. If no resource view was set for texObject, the MUSA_ERROR_INVALID_VALUE is returned.

Parameters

  • pResViewDesc (MUSA_RESOURCE_VIEW_DESC *): Resource view descriptor
  • texObject (MUtexObject): Texture object

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

3.27 Surface Object Management​

muSurfObjectCreate​

MUresult muSurfObjectCreate(MUsurfObject *pSurfObject, const MUSA_RESOURCE_DESC *pResDesc)

Description

  • Creates a surface object.
  • Creates a surface object and returns it in pSurfObject. pResDesc describes the data to perform surface load/stores on. MUSA_RESOURCE_DESC::resType must be MU_RESOURCE_TYPE_ARRAY and MUSA_RESOURCE_DESC::res::array::hArray must be set to a valid MUSA array handle. MUSA_RESOURCE_DESC::flags must be set to zero.
  • Surface objects are only supported on devices of compute capability 3.0 or higher. Additionally, a surface object is an opaque value, and, as such, should only be accessed through MUSA API calls.

Parameters

  • pSurfObject (MUsurfObject *): Surface object to create
  • pResDesc (const MUSA_RESOURCE_DESC *): Resource descriptor

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muSurfObjectDestroy​

MUresult muSurfObjectDestroy(MUsurfObject surfObject)

Description

  • Destroys a surface object.
  • Destroys the surface object specified by surfObject.

Parameters

  • surfObject (MUsurfObject): Surface object to destroy

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muSurfObjectGetResourceDesc​

MUresult muSurfObjectGetResourceDesc(MUSA_RESOURCE_DESC *pResDesc, MUsurfObject surfObject)

Description

  • Returns a surface object's resource descriptor.
  • Returns the resource descriptor for the surface object specified by surfObject.

Parameters

  • pResDesc (MUSA_RESOURCE_DESC *): Resource descriptor
  • surfObject (MUsurfObject): Surface object

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

3.28 Tensor Map Object Management​

muTensorDescriptorEncode​

MUresult muTensorDescriptorEncode(MUtensorDescriptor *tensorDesc, MUtensorDescriptorDataType tensorDataType, muuint32_t tensorRank, void *globalAddress, const muuint64_t *globalDim, const muuint64_t *globalStrides, MUtensorDescriptorInterleave interleave, muuint64_t oobConstantFill)

Description

  • No description is available.

Parameters

  • tensorDesc (MUtensorDescriptor *)
  • tensorDataType (MUtensorDescriptorDataType)
  • tensorRank (muuint32_t)
  • globalAddress (void *)
  • globalDim (const muuint64_t *)
  • globalStrides (const muuint64_t *)
  • interleave (MUtensorDescriptorInterleave)
  • oobConstantFill (muuint64_t)

Returns

  • Return type: MUresult.

muTensorDescriptorReplaceAddress​

MUresult muTensorDescriptorReplaceAddress(MUtensorDescriptor *tensorDesc, void *globalAddress)

Description

  • No description is available.

Parameters

  • tensorDesc (MUtensorDescriptor *)
  • globalAddress (void *)

Returns

  • Return type: MUresult.

muTensorIm2colConvParamEncode​

MUresult muTensorIm2colConvParamEncode(MUconvParamer *convParam, muuint32_t convRank, const muuint32_t *padding, const muuint32_t *stride, const muuint32_t *dilation)

Description

  • No description is available.

Parameters

  • convParam (MUconvParamer *)
  • convRank (muuint32_t)
  • padding (const muuint32_t *)
  • stride (const muuint32_t *)
  • dilation (const muuint32_t *)

Returns

  • Return type: MUresult.

muTensorDirectConvEncode​

MUresult muTensorDirectConvEncode(MUdirectConvParamer *param, muuint32_t convRank, const muuint32_t *inputImageDim, const muuint32_t *inputImageStrides, const muuint32_t *weightDim, const muuint32_t *weightStrides, const muuint32_t *paddings, const muuint32_t *strides, MUdirectConvInterleave inputImageInterelave, MUdirectConvInterleave weightInterelave, muuint32_t imageSwizzle, muuint32_t weightSwizzle, muuint32_t constantFillValue, MUdirectConvBasicShape shape)

Description

  • No description is available.

Parameters

  • param (MUdirectConvParamer *)
  • convRank (muuint32_t)
  • inputImageDim (const muuint32_t *)
  • inputImageStrides (const muuint32_t *)
  • weightDim (const muuint32_t *)
  • weightStrides (const muuint32_t *)
  • paddings (const muuint32_t *)
  • strides (const muuint32_t *)
  • inputImageInterelave (MUdirectConvInterleave)
  • weightInterelave (MUdirectConvInterleave)
  • imageSwizzle (muuint32_t)
  • weightSwizzle (muuint32_t)
  • constantFillValue (muuint32_t)
  • shape (MUdirectConvBasicShape)

Returns

  • Return type: MUresult.

3.29 Peer Context Memory Access​

muDeviceCanAccessPeer​

MUresult muDeviceCanAccessPeer(int *canAccessPeer, MUdevice dev, MUdevice peerDev)

Description

  • Queries if a device may directly access a peer device's memory.
  • Returns in *canAccessPeer a value of 1 if contexts on dev are capable of directly accessing memory from contexts on peerDev and 0 otherwise. If direct access of peerDev from dev is possible, then access may be enabled on two specific contexts by calling muCtxEnablePeerAccess().

Parameters

  • canAccessPeer (int *): Returned access capability
  • dev (MUdevice): Device from which allocations on peerDev are to be directly accessed.
  • peerDev (MUdevice): Device on which the allocations to be directly accessed by dev reside.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxEnablePeerAccess​

MUresult muCtxEnablePeerAccess(MUcontext peerContext, unsigned int Flags)

Description

  • Enables direct access to memory allocations in a peer context.
  • If both the current context and peerContext are on devices which support unified addressing (as may be queried using MU_DEVICE_ATTRIBUTE_UNIFIED_ADDRESSING) and same major compute capability, then on success all allocations from peerContext will immediately be accessible by the current context. See Unified Addressing for additional details.
  • Note that access granted by this call is unidirectional and that in order to access memory from the current context in peerContext, a separate symmetric call to muCtxEnablePeerAccess() is required.
  • Note that there are both device-wide and system-wide limitations per system configuration, as noted in the MUSA Programming Guide under the section "Peer-to-Peer Memory Access".
  • Returns MUSA_ERROR_PEER_ACCESS_UNSUPPORTED if muDeviceCanAccessPeer() indicates that the MUdevice of the current context cannot directly access memory from the MUdevice of peerContext.
  • Returns MUSA_ERROR_PEER_ACCESS_ALREADY_ENABLED if direct access of peerContext from the current context has already been enabled.
  • Returns MUSA_ERROR_TOO_MANY_PEERS if direct peer access is not possible because hardware resources required for peer access have been exhausted.
  • Returns MUSA_ERROR_INVALID_CONTEXT if there is no current context, peerContext is not a valid context, or if the current context is peerContext.
  • Returns MUSA_ERROR_INVALID_VALUE if Flags is not 0.

Parameters

  • peerContext (MUcontext): Peer context to enable direct access to from the current context
  • Flags (unsigned int): Reserved for future use and must be set to 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_PEER_ACCESS_ALREADY_ENABLED, MUSA_ERROR_TOO_MANY_PEERS, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_PEER_ACCESS_UNSUPPORTED, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muCtxDisablePeerAccess​

MUresult muCtxDisablePeerAccess(MUcontext peerContext)

Description

  • Disables direct access to memory allocations in a peer context and unregisters any registered allocations.
  • Returns MUSA_ERROR_PEER_ACCESS_NOT_ENABLED if direct peer access has not yet been enabled from peerContext to the current context.
  • Returns MUSA_ERROR_INVALID_CONTEXT if there is no current context, or if peerContext is not a valid context.

Parameters

  • peerContext (MUcontext): Peer context to disable direct access to

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_PEER_ACCESS_NOT_ENABLED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muDeviceGetP2PAttribute​

MUresult muDeviceGetP2PAttribute(int *value, MUdevice_P2PAttribute attrib, MUdevice srcDevice, MUdevice dstDevice)

Description

  • Queries attributes of the link between two devices.
  • Returns in *value the value of the requested attribute attrib of the link between srcDevice and dstDevice. The supported attributes are: MU_DEVICE_P2P_ATTRIBUTE_PERFORMANCE_RANK: A relative value indicating the performance of the link between two devices. MU_DEVICE_P2P_ATTRIBUTE_ACCESS_SUPPORTED P2P: 1 if P2P Access is enable. MU_DEVICE_P2P_ATTRIBUTE_NATIVE_ATOMIC_SUPPORTED: 1 if Atomic operations over the link are supported. MU_DEVICE_P2P_ATTRIBUTE_MUSA_ARRAY_ACCESS_SUPPORTED: 1 if musaArray can be accessed over the link. MU_DEVICE_P2P_ATTRIBUTE_ONLY_PARTIAL_NATIVE_ATOMIC_SUPPORTED: 1 if some MUSA-valid atomic operations over the link are supported. Information about specific operations can be retrieved with muDeviceGetP2PAtomicCapabilities.
  • Returns MUSA_ERROR_INVALID_DEVICE if srcDevice or dstDevice are not valid or if they represent the same device.
  • Returns MUSA_ERROR_INVALID_VALUE if attrib is not valid or if value is a null pointer.

Parameters

  • value (int *): Returned value of the requested attribute
  • attrib (MUdevice_P2PAttribute): The requested attribute of the link between srcDevice and dstDevice.
  • srcDevice (MUdevice): The source device of the target link.
  • dstDevice (MUdevice): The destination device of the target link.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.30 Graphics Interoperability​

muGraphicsUnregisterResource​

MUresult muGraphicsUnregisterResource(MUgraphicsResource resource)

Description

  • Unregisters a graphics resource for access by MUSA.
  • Unregisters the graphics resource resource so it is not accessible by MUSA unless registered again.
  • If resource is invalid then MUSA_ERROR_INVALID_HANDLE is returned.

Parameters

  • resource (MUgraphicsResource): Resource to unregister

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_UNKNOWN

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsSubResourceGetMappedArray​

MUresult muGraphicsSubResourceGetMappedArray(MUarray *pArray, MUgraphicsResource resource, unsigned int arrayIndex, unsigned int mipLevel)

Description

  • Get an array through which to access a subresource of a mapped graphics resource.
  • Returns in *pArray an array through which the subresource of the mapped graphics resource resource which corresponds to array index arrayIndex and mipmap level mipLevel may be accessed. The value set in *pArray may change every time that resource is mapped.
  • If resource is not a texture then it cannot be accessed via an array and MUSA_ERROR_NOT_MAPPED_AS_ARRAY is returned. If arrayIndex is not a valid array index for resource then MUSA_ERROR_INVALID_VALUE is returned. If mipLevel is not a valid mipmap level for resource then MUSA_ERROR_INVALID_VALUE is returned. If resource is not mapped then MUSA_ERROR_NOT_MAPPED is returned.

Parameters

  • pArray (MUarray *): Returned array through which a subresource of resource may be accessed
  • resource (MUgraphicsResource): Mapped resource to access
  • arrayIndex (unsigned int): Array index for array textures or cubemap face index as defined by MUarray_cubemap_face for cubemap textures for the subresource to access
  • mipLevel (unsigned int): Mipmap level for the subresource to access

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_MAPPED, MUSA_ERROR_NOT_MAPPED_AS_ARRAY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsResourceGetMappedMipmappedArray​

MUresult muGraphicsResourceGetMappedMipmappedArray(MUmipmappedArray *pMipmappedArray, MUgraphicsResource resource)

Description

  • Get a mipmapped array through which to access a mapped graphics resource.
  • Returns in *pMipmappedArray a mipmapped array through which the mapped graphics resource resource. The value set in *pMipmappedArray may change every time that resource is mapped.
  • If resource is not a texture then it cannot be accessed via a mipmapped array and MUSA_ERROR_NOT_MAPPED_AS_ARRAY is returned. If resource is not mapped then MUSA_ERROR_NOT_MAPPED is returned.

Parameters

  • pMipmappedArray (MUmipmappedArray *): Returned mipmapped array through which resource may be accessed
  • resource (MUgraphicsResource): Mapped resource to access

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_MAPPED, MUSA_ERROR_NOT_MAPPED_AS_ARRAY

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsResourceGetMappedPointer​

MUresult muGraphicsResourceGetMappedPointer(MUdeviceptr *pDevPtr, size_t *pSize, MUgraphicsResource resource)

Description

  • Get a device pointer through which to access a mapped graphics resource.
  • Returns in *pDevPtr a pointer through which the mapped graphics resource resource may be accessed. Returns in pSize the size of the memory in bytes which may be accessed from that pointer. The value set in pPointer may change every time that resource is mapped.
  • If resource is not a buffer then it cannot be accessed via a pointer and MUSA_ERROR_NOT_MAPPED_AS_POINTER is returned. If resource is not mapped then MUSA_ERROR_NOT_MAPPED is returned. pDevPtr - Returned pointer through which resource may be accessed pSize - Returned size of the buffer accessible starting at *pPointer resource - Mapped resource to access MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_MAPPED, MUSA_ERROR_NOT_MAPPED_AS_POINTER This function may also return error codes from previous, asynchronous launches. muGraphicsMapResources, muGraphicsSubResourceGetMappedArray, musaGraphicsResourceGetMappedPointer

Parameters

  • pDevPtr (MUdeviceptr *): Returned pointer through which resource may be accessed
  • pSize (size_t *): Returned size of the buffer accessible starting at *pPointer
  • resource (MUgraphicsResource): Mapped resource to access

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_MAPPED, MUSA_ERROR_NOT_MAPPED_AS_POINTER

Note

  • Additional exported symbol names in scope: muGraphicsResourceGetMappedPointer_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsResourceSetMapFlags​

MUresult muGraphicsResourceSetMapFlags(MUgraphicsResource resource, unsigned int flags)

Description

  • Set usage flags for mapping a graphics resource.
  • Set flags for mapping the graphics resource resource.
  • Changes to flags will take effect the next time resource is mapped. The flags argument may be any of the following:
  • MU_GRAPHICS_MAP_RESOURCE_FLAGS_NONE: Specifies no hints about how this resource will be used. It is therefore assumed that this resource will be read from and written to by MUSA kernels. This is the default value. MU_GRAPHICS_MAP_RESOURCE_FLAGS_READONLY: Specifies that MUSA kernels which access this resource will not write to this resource. MU_GRAPHICS_MAP_RESOURCE_FLAGS_WRITEDISCARD: Specifies that MUSA kernels which access this resource will not read from this resource and will write over the entire contents of the resource, so none of the data previously stored in the resource will be preserved.
  • If resource is presently mapped for access by MUSA then MUSA_ERROR_ALREADY_MAPPED is returned. If flags is not one of the above values then MUSA_ERROR_INVALID_VALUE is returned.

Parameters

  • resource (MUgraphicsResource): Registered resource to set flags for
  • flags (unsigned int): Parameters for resource mapping

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ALREADY_MAPPED

Note

  • Additional exported symbol names in scope: muGraphicsResourceSetMapFlags_v2.
  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsMapResources​

MUresult muGraphicsMapResources(unsigned int count, MUgraphicsResource *resources, MUstream hStream)

Description

  • Map graphics resources for access by MUSA.
  • Maps the count graphics resources in resources for access by MUSA.
  • The resources in resources may be accessed by MUSA until they are unmapped. The graphics API from which resources were registered should not access any resources while they are mapped by MUSA. If an application does so, the results are undefined.
  • This function provides the synchronization guarantee that any graphics calls issued before muGraphicsMapResources() will complete before any subsequent MUSA work issued in stream begins.
  • If resources includes any duplicate entries then MUSA_ERROR_INVALID_HANDLE is returned. If any of resources are presently mapped for access by MUSA then MUSA_ERROR_ALREADY_MAPPED is returned.

Parameters

  • count (unsigned int): Number of resources to map
  • resources (MUgraphicsResource *): Resources to map for MUSA usage
  • hStream (MUstream): Stream with which to synchronize

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ALREADY_MAPPED, MUSA_ERROR_UNKNOWN

Note

  • Additional exported symbol names in scope: muGraphicsMapResources_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

muGraphicsUnmapResources​

MUresult muGraphicsUnmapResources(unsigned int count, MUgraphicsResource *resources, MUstream hStream)

Description

  • Unmap graphics resources.
  • Unmaps the count graphics resources in resources.
  • Once unmapped, the resources in resources may not be accessed by MUSA until they are mapped again.
  • This function provides the synchronization guarantee that any MUSA work issued in stream before muGraphicsUnmapResources() will complete before any subsequently issued graphics work begins.
  • If resources includes any duplicate entries then MUSA_ERROR_INVALID_HANDLE is returned. If any of resources are not presently mapped for access by MUSA then MUSA_ERROR_NOT_MAPPED is returned.

Parameters

  • count (unsigned int): Number of resources to unmap
  • resources (MUgraphicsResource *): Resources to unmap
  • hStream (MUstream): Stream with which to synchronize

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_NOT_MAPPED, MUSA_ERROR_UNKNOWN

Note

  • Additional exported symbol names in scope: muGraphicsUnmapResources_ptsz.
  • This function may also return error codes from previous, asynchronous launches.
  • See the default-stream note for NULL stream semantics.

See also

3.31 Driver Entry Point Access​

muGetProcAddress​

MUresult muGetProcAddress(const char *symbol, void **pfn, int musaVersion, muuint64_t flags, MUdriverProcAddressQueryResult *symbolStatus)

Description

  • Returns the requested driver API function pointer.
  • Returns in **pfn the address of the MUSA driver function for the requested MUSA version and flags.
  • The MUSA version is specified as (1000 * major + 10 * minor), so MUSA 11.2 should be specified as 11020. For a requested driver symbol, if the specified MUSA version is greater than or equal to the MUSA version in which the driver symbol was introduced, this API will return the function pointer to the corresponding versioned function.
  • The pointer returned by the API should be cast to a function pointer matching the requested driver function's definition in the API header file. The function pointer typedef can be picked up from the corresponding typedefs header file. For example, musaTypedefs.h consists of function pointer typedefs for driver APIs defined in musa.h.
  • The API will return MUSA_SUCCESS and set the returned pfn to NULL if the requested driver function is not supported on the platform, no ABI compatible driver function exists for the specified musaVersion or if the driver symbol is invalid.
  • It will also set the optional symbolStatus to one of the values in MUdriverProcAddressQueryResult with the following meanings: MU_GET_PROC_ADDRESS_SUCCESS - The requested symbol was succesfully found based on input arguments and pfn is valid MU_GET_PROC_ADDRESS_SYMBOL_NOT_FOUND - The requested symbol was not found MU_GET_PROC_ADDRESS_VERSION_NOT_SUFFICIENT - The requested symbol was found but is not supported by musaVersion specified
  • The requested flags can be: MU_GET_PROC_ADDRESS_DEFAULT: This is the default mode. This is equivalent to MU_GET_PROC_ADDRESS_PER_THREAD_DEFAULT_STREAM if the code is compiled with default-stream per-thread compilation flag or the macro MUSA_API_PER_THREAD_DEFAULT_STREAM is defined; MU_GET_PROC_ADDRESS_LEGACY_STREAM otherwise. MU_GET_PROC_ADDRESS_LEGACY_STREAM: This will enable the search for all driver symbols that match the requested driver symbol name except the corresponding per-thread versions. MU_GET_PROC_ADDRESS_PER_THREAD_DEFAULT_STREAM: This will enable the search for all driver symbols that match the requested driver symbol name including the per-thread versions. If a per-thread version is not found, the API will return the legacy version of the driver function.

Parameters

  • symbol (const char *): The base name of the driver API function to look for. As an example, for the driver API muMemAlloc_v2, symbol would be muMemAlloc and musaVersion would be the ABI compatible MUSA version for the _v2 variant.
  • pfn (void **): Location to return the function pointer to the requested driver function
  • musaVersion (int): The MUSA version to look for the requested driver symbol
  • flags (muuint64_t): Flags to specify search options.
  • symbolStatus (MUdriverProcAddressQueryResult *): Optional location to store the status of the search for symbol based on musaVersion. See MUdriverProcAddressQueryResult for possible values.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED

Note

  • Additional exported symbol names in scope: muGetProcAddress_v2.
  • See the API version mixing note in the toolkit documentation.

See also

3.32 Memory Atomic Management​

muMemoryAtomicAsync​

MUresult muMemoryAtomicAsync(MUdeviceptr dst, MUdeviceptr src, size_t elementCount, MUatomicType operation, MUstream hStream)

Description

  • Memory atomic from Device to Device.
  • Perform memory atomic operation from device memory to device memory. dst and src are base pointers of the destination and source, respectively. elementCount specifies the number of elements to perform memory atomic.

Parameters

  • dst (MUdeviceptr): Destination device pointer
  • src (MUdeviceptr): Source device pointer
  • elementCount (size_t): Size of memory atomic in elements
  • operation (MUatomicType): Specifies which atomic operation to perform, include element size. See MUatomicType
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

muMemoryAtomicValueAsync​

MUresult muMemoryAtomicValueAsync(MUdeviceptr dst, muuint64_t value, MUatomicValueType operation, MUstream hStream)

Description

  • Memory atomic value.
  • Perform memory atomic value operation to device memory range of 64-bit values.

Parameters

  • dst (MUdeviceptr): Destination device pointer
  • value (muuint64_t): data value for the atomic operation
  • operation (MUatomicValueType): Specifies which atomic operation to perform. See MUatomicValueType
  • hStream (MUstream): Stream identifier

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.
  • See the API synchronization behavior notes for asynchronous host/device behavior.
  • See the default-stream note for NULL stream semantics.

3.33 Coredump Attributes Control API​

muCoredumpGetAttribute​

MUresult muCoredumpGetAttribute(MUcoredumpSettings attrib, void *value, size_t *size)

Description

  • Allows caller to fetch a coredump attribute value for the current context.
  • Returns in *value the requested value specified by attrib. It is up to the caller to ensure that the data type and size of *value matches the request.
  • If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes) expected for attrib will be placed in size.
  • The supported attributes are: MU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions from this context will create a coredump at the location specified by MU_COREDUMP_FILE. The default value is false unless set to true globally or locally, or the MU_CTX_USER_COREDUMP_ENABLE flag was set during context creation. MU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create a coredump. The default value is true unless set to false globally or or locally. This value is deprecated as of MUSA 12.5 - raise the MU_COREDUMP_SKIP_ABORT flag to disable host device abort() if needed. MU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not have a dump of GPU memory or non-reloc ELF images. The default value is false unless set to true globally or locally. This attribute is deprecated as of MUSA 12.5, please use MU_COREDUMP_GENERATION_FLAGS instead. MU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be created by writing to the system pipe specified by MU_COREDUMP_PIPE. The default value is false unless set to true globally or locally. MU_COREDUMP_FILE: String of up to 1023 characters that defines the location where any coredumps generated by this context will be written. The default value is core.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA applications and PID is the process ID of the MUSA application. MU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the pipe that will be monitored if user-triggered coredumps are enabled. The default value is corepipe.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA application and PID is the process ID of the MUSA application. MU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular control the data contained in a coredump specified as a bitwise OR combination of the following values: MU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump generation returns to its default settings of including all memory regions that it is able to access MU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump will not include the data from MUSA source modules that are not relocated at runtime. MU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global data that does not belong to any context. MU_COREDUMP_SKIP_SHARED_MEMORY - Coredump will not include grid-scale shared memory for the warp that the dumped kernel belonged to. MU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local memory from the kernel. MU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the above options. Equiavlent to setting the MU_COREDUMP_LIGHTWEIGHT attribute to true. MU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host CPU process. Same functional goal as MU_COREDUMP_TRIGGER_HOST but better reflects the default behavior.

Parameters

  • attrib (MUcoredumpSettings): The enum defining which value to fetch.
  • value (void ): void containing the requested data.
  • size (size_t *): The size of the memory region value points to.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED

See also

muCoredumpGetAttributeGlobal​

MUresult muCoredumpGetAttributeGlobal(MUcoredumpSettings attrib, void *value, size_t *size)

Description

  • Allows caller to fetch a coredump attribute value for the entire application.
  • Returns in *value the requested value specified by attrib. It is up to the caller to ensure that the data type and size of *value matches the request.
  • If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes) expected for attrib will be placed in size.
  • The supported attributes are: MU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions from this context will create a coredump at the location specified by MU_COREDUMP_FILE. The default value is false. MU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create a coredump. The default value is true unless set to false globally or or locally. This value is deprecated as of MUSA 12.5 - raise the MU_COREDUMP_SKIP_ABORT flag to disable host device abort() if needed. MU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is deprecated as of MUSA 12.5, please use MU_COREDUMP_GENERATION_FLAGS instead. MU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be created by writing to the system pipe specified by MU_COREDUMP_PIPE. The default value is false. MU_COREDUMP_FILE: String of up to 1023 characters that defines the location where any coredumps generated by this context will be written. The default value is core.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA applications and PID is the process ID of the MUSA application. MU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the pipe that will be monitored if user-triggered coredumps are enabled. The default value is corepipe.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA application and PID is the process ID of the MUSA application. MU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular control the data contained in a coredump specified as a bitwise OR combination of the following values: MU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump generation returns to its default settings of including all memory regions that it is able to access MU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump will not include the data from MUSA source modules that are not relocated at runtime. MU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global data that does not belong to any context. MU_COREDUMP_SKIP_SHARED_MEMORY - Coredump will not include grid-scale shared memory for the warp that the dumped kernel belonged to. MU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local memory from the kernel. MU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the above options. Equiavlent to setting the MU_COREDUMP_LIGHTWEIGHT attribute to true. MU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host CPU process. Same functional goal as MU_COREDUMP_TRIGGER_HOST but better reflects the default behavior.

Parameters

  • attrib (MUcoredumpSettings): The enum defining which value to fetch.
  • value (void ): void containing the requested data.
  • size (size_t *): The size of the memory region value points to.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

See also

muCoredumpSetAttribute​

MUresult muCoredumpSetAttribute(MUcoredumpSettings attrib, void *value, size_t *size)

Description

  • Allows caller to set a coredump attribute value for the current context.
  • This function should be considered an alternate interface to the MUSA-GDB environment variables defined in this document: https://docs.mthreads.com/musa/musa-gdb/index.html#gpu-coredump
  • An important design decision to note is that any coredump environment variable values set before MUSA initializes will take permanent precedence over any values set with this function. This decision was made to ensure no change in behavior for any users that may be currently using these variables to get coredumps.
  • *value shall contain the requested value specified by set. It is up to the caller to ensure that the data type and size of *value matches the request.
  • If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes) expected for set will be placed in size.
  • /note This function will return MUSA_ERROR_NOT_SUPPORTED if the caller attempts to set MU_COREDUMP_ENABLE_ON_EXCEPTION on a GPU of with Compute Capability < 6.0. muCoredumpSetAttributeGlobal works on those platforms as an alternative.
  • /note MU_COREDUMP_ENABLE_USER_TRIGGER and MU_COREDUMP_PIPE cannot be set on a per-context basis.
  • The supported attributes are: MU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions from this context will create a coredump at the location specified by MU_COREDUMP_FILE. The default value is false. MU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create a coredump. The default value is true unless set to false globally or or locally. This value is deprecated as of MUSA 12.5 - raise the MU_COREDUMP_SKIP_ABORT flag to disable host device abort() if needed. MU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is deprecated as of MUSA 12.5, please use MU_COREDUMP_GENERATION_FLAGS instead. MU_COREDUMP_FILE: String of up to 1023 characters that defines the location where any coredumps generated by this context will be written. The default value is core.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA applications and PID is the process ID of the MUSA application. MU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular control the data contained in a coredump specified as a bitwise OR combination of the following values: MU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump generation returns to its default settings of including all memory regions that it is able to access MU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump will not include the data from MUSA source modules that are not relocated at runtime. MU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global data that does not belong to any context. MU_COREDUMP_SKIP_SHARED_MEMORY - Coredump will not include grid-scale shared memory for the warp that the dumped kernel belonged to. MU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local memory from the kernel. MU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the above options. Equiavlent to setting the MU_COREDUMP_LIGHTWEIGHT attribute to true. MU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host CPU process. Same functional goal as MU_COREDUMP_TRIGGER_HOST but better reflects the default behavior.

Parameters

  • attrib (MUcoredumpSettings): The enum defining which value to set.
  • value (void ): void containing the requested data.
  • size (size_t *): The size of the memory region value points to.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_PERMITTED, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED, MUSA_ERROR_NOT_SUPPORTED

See also

muCoredumpSetAttributeGlobal​

MUresult muCoredumpSetAttributeGlobal(MUcoredumpSettings attrib, void *value, size_t *size)

Description

  • Allows caller to set a coredump attribute value globally.
  • This function should be considered an alternate interface to the MUSA-GDB environment variables defined in this document: https://docs.mthreads.com/musa/musa-gdb/index.html#gpu-coredump
  • An important design decision to note is that any coredump environment variable values set before MUSA initializes will take permanent precedence over any values set with this function. This decision was made to ensure no change in behavior for any users that may be currently using these variables to get coredumps.
  • *value shall contain the requested value specified by set. It is up to the caller to ensure that the data type and size of *value matches the request.
  • If the caller calls this function with *value equal to NULL, the size of the memory region (in bytes) expected for set will be placed in size.
  • The supported attributes are: MU_COREDUMP_ENABLE_ON_EXCEPTION: Bool where true means that GPU exceptions from this context will create a coredump at the location specified by MU_COREDUMP_FILE. The default value is false. MU_COREDUMP_TRIGGER_HOST: Bool where true means that the host CPU will also create a coredump. The default value is true unless set to false globally or or locally. This value is deprecated as of MUSA 12.5 - raise the MU_COREDUMP_SKIP_ABORT flag to disable host device abort() if needed. MU_COREDUMP_LIGHTWEIGHT: Bool where true means that any resulting coredumps will not have a dump of GPU memory or non-reloc ELF images. The default value is false. This attribute is deprecated as of MUSA 12.5, please use MU_COREDUMP_GENERATION_FLAGS instead. MU_COREDUMP_ENABLE_USER_TRIGGER: Bool where true means that a coredump can be created by writing to the system pipe specified by MU_COREDUMP_PIPE. The default value is false. MU_COREDUMP_FILE: String of up to 1023 characters that defines the location where any coredumps generated by this context will be written. The default value is core.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA applications and PID is the process ID of the MUSA application. MU_COREDUMP_PIPE: String of up to 1023 characters that defines the name of the pipe that will be monitored if user-triggered coredumps are enabled. This value may not be changed after MU_COREDUMP_ENABLE_USER_TRIGGER is set to true. The default value is corepipe.musa.HOSTNAME.PID where HOSTNAME is the host name of the machine running the MUSA application and PID is the process ID of the MUSA application. MU_COREDUMP_GENERATION_FLAGS: An integer with values to allow granular control the data contained in a coredump specified as a bitwise OR combination of the following values: MU_COREDUMP_DEFAULT_FLAGS - if set by itself, coredump generation returns to its default settings of including all memory regions that it is able to access MU_COREDUMP_SKIP_NONRELOCATED_ELF_IMAGES - Coredump will not include the data from MUSA source modules that are not relocated at runtime. MU_COREDUMP_SKIP_GLOBAL_MEMORY - Coredump will not include device-side global data that does not belong to any context. MU_COREDUMP_SKIP_SHARED_MEMORY - Coredump will not include grid-scale shared memory for the warp that the dumped kernel belonged to. MU_COREDUMP_SKIP_LOCAL_MEMORY - Coredump will not include local memory from the kernel. MU_COREDUMP_LIGHTWEIGHT_FLAGS - Enables all of the above options. Equiavlent to setting the MU_COREDUMP_LIGHTWEIGHT attribute to true. MU_COREDUMP_SKIP_ABORT - If set, GPU exceptions will not raise an abort() in the host CPU process. Same functional goal as MU_COREDUMP_TRIGGER_HOST but better reflects the default behavior.

Parameters

  • attrib (MUcoredumpSettings): The enum defining which value to set.
  • value (void ): void containing the requested data.
  • size (size_t *): The size of the memory region value points to.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_PERMITTED

See also

3.34 Green Contexts​

muGreenCtxCreate​

MUresult muGreenCtxCreate(MUgreenCtx *phCtx, MUdevResourceDesc desc, MUdevice dev, unsigned int flags)

Description

  • Creates a green context with a specified set of resources.
  • This API creates a green context with the resources specified in the descriptor desc and returns it in the handle represented by phCtx. This API will retain the primary context on device dev, which will is released when the green context is destroyed. It is advised to have the primary context active before calling this API to avoid the heavy cost of triggering primary context initialization and deinitialization multiple times.
  • The API does not set the green context current. In order to set it current, you need to explicitly set it current by first converting the green context to a MUcontext using muCtxFromGreenCtx and subsequently calling muCtxSetCurrent / muCtxPushCurrent. It should be noted that a green context can be current to only one thread at a time. There is no internal synchronization to make API calls accessing the same green context from multiple threads work.
  • Note: The API is not supported on 32-bit platforms.

Parameters

  • phCtx (MUgreenCtx *): Pointer for the output handle to the green context
  • desc (MUdevResourceDesc): Descriptor generated via muDevResourceGenerateDesc which contains the set of resources to be used
  • dev (MUdevice): Device on which to create the green context.
  • flags (unsigned int): One of the supported green context creation flags. MU_GREEN_CTX_DEFAULT_STREAM is required.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_NOT_SUPPORTED, MUSA_ERROR_OUT_OF_MEMORY

See also

muGreenCtxDestroy​

MUresult muGreenCtxDestroy(MUgreenCtx hCtx)

Description

  • Destroys a green context.
  • Destroys the green context, releasing the primary context of the device that this green context was created for. Any resources provisioned for this green context (that were initially available via the resource descriptor) are released as well. The API does not destroy streams created via muGreenCtxStreamCreate, muStreamCreate, or muStreamCreateWithPriority. Users are expected to destroy these streams explicitly using muStreamDestroy to avoid resource leaks. Once the green context is destroyed, any subsequent API calls involving these streams will return MUSA_ERROR_STREAM_DETACHED with the exception of the following APIs: muStreamDestroy.
  • Additionally, the API will invalidate all active captures on these streams.

Parameters

  • hCtx (MUgreenCtx): Green context to be destroyed

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_CONTEXT_IS_DESTROYED

See also

muCtxFromGreenCtx​

MUresult muCtxFromGreenCtx(MUcontext *pContext, MUgreenCtx hCtx)

Description

  • Converts a green context into the primary context.
  • The API converts a green context into the primary context returned in pContext. It is important to note that the converted context pContext is a normal primary context but with the resources of the specified green context hCtx. Once converted, it can then be used to set the context current with muCtxSetCurrent or with any of the MUSA APIs that accept a MUcontext parameter.
  • Users are expected to call this API before calling any MUSA APIs that accept a MUcontext. Failing to do so will result in the APIs returning MUSA_ERROR_INVALID_CONTEXT.

Parameters

  • pContext (MUcontext *): Returned primary context with green context resources
  • hCtx (MUgreenCtx): Green context to convert

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE

See also

muDeviceGetDevResource​

MUresult muDeviceGetDevResource(MUdevice device, MUdevResource *resource, MUdevResourceType type)

Description

  • Get device resources.
  • Get the type resources available to the device. This may often be the starting point for further partitioning or configuring of resources.
  • Note: The API is not supported on 32-bit platforms.

Parameters

  • device (MUdevice): Device to get resource for
  • resource (MUdevResource *): Output pointer to a MUdevResource structure
  • type (MUdevResourceType): Type of resource to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_DEVICE

See also

muCtxGetDevResource​

MUresult muCtxGetDevResource(MUcontext hCtx, MUdevResource *resource, MUdevResourceType type)

Description

  • Get context resources.

Parameters

  • hCtx (MUcontext): Context to get resource for
  • resource (MUdevResource *): Output pointer to a MUdevResource structure
  • type (MUdevResourceType): Type of resource to retrieve

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_CONTEXT

See also

muGreenCtxGetDevResource​

MUresult muGreenCtxGetDevResource(MUgreenCtx hCtx, MUdevResource *resource, MUdevResourceType type)

Description

  • Get green context resources.

Parameters

  • hCtx (MUgreenCtx): Green context to get resource for
  • resource (MUdevResource *): Output pointer to a MUdevResource structure
  • type (MUdevResourceType): Type of resource to retrieve

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_VALUE

See also

muDevSmResourceSplitByCount​

MUresult muDevSmResourceSplitByCount(MUdevResource *result, unsigned int *nbGroups, const MUdevResource *input, MUdevResource *remaining, unsigned int useFlags, unsigned int minCount)

Description

  • Splits MU_DEV_RESOURCE_TYPE_SM resources.
  • Splits MU_DEV_RESOURCE_TYPE_SM resources into nbGroups, adhering to the minimum SM count specified in minCount and the usage flags in useFlags. If result is NULL, the API simulates a split and provides the amount of groups that would be created in nbGroups. Otherwise, nbGroups must point to the amount of elements in result and on return, the API will overwrite nbGroups with the amount actually created. The groups are written to the array in result. nbGroups can be less than the total amount if a smaller number of groups is needed.
  • This API is used to spatially partition the input resource. The input resource needs to come from one of muDeviceGetDevResource, muCtxGetDevResource, or muGreenCtxGetDevResource. A limitation of the API is that the output results cannot be split again without first creating a descriptor and a green context with that descriptor.
  • When creating the groups, the API will take into account the performance and functional characteristics of the input resource, and guarantee a split that will create a disjoint set of symmetrical partitions. This may lead to fewer groups created than purely dividing the total SM count by the minCount due to cluster requirements or alignment and granularity requirements for the minCount. These requirements can be queried with muDeviceGetDevResource, muCtxGetDevResource, and muGreenCtxGetDevResource for MU_DEV_RESOURCE_TYPE_SM, using the minSmPartitionSize and smCoscheduledAlignment fields to determine minimum partition size and alignment granularity, respectively.
  • The remainder set does not have the same functional or performance guarantees as the groups in result. Its use should be carefully planned and future partitions of the remainder set are discouraged.
  • The following flags are supported: MU_DEV_SM_RESOURCE_SPLIT_IGNORE_SM_COSCHEDULING : Lower the minimum SM count and alignment, and treat each SM independent of its hierarchy. This allows more fine grained partitions but at the cost of advanced features (such as large clusters on compute capability 9.0+). MU_DEV_SM_RESOURCE_SPLIT_MAX_POTENTIAL_CLUSTER_SIZE : Compute Capability 9.0+ only. Attempt to create groups that may allow for maximally sized thread clusters. This can be queried post green context creation using muOccupancyMaxPotentialClusterSize.
  • A successful API call must either have: A valid array of result pointers of size passed in nbGroups, with input of type MU_DEV_RESOURCE_TYPE_SM. Value of minCount must be between 0 and the SM count specified in input. remaining may be NULL. NULL passed in for result, with a valid integer pointer in nbGroups and input of type MU_DEV_RESOURCE_TYPE_SM. Value of minCount must be between 0 and the SM count specified in input. remaining may be NULL. This queries the number of groups that would be created by the API.
  • Note: The API is not supported on 32-bit platforms.

Parameters

  • result (MUdevResource *): Output array of MUdevResource resources. Can be NULL to query the number of groups.
  • nbGroups (unsigned int *): This is a pointer, specifying the number of groups that would be or should be created as described below.
  • input (const MUdevResource *): Input SM resource to be split. Must be a valid MU_DEV_RESOURCE_TYPE_SM resource.
  • remaining (MUdevResource *): If the input resource cannot be cleanly split among nbGroups, the remaining is placed in here. Can be ommitted (NULL) if the user does not need the remaining set.
  • useFlags (unsigned int): Flags specifying how these partitions are used or which constraints to abide by when splitting the input. Zero is valid for default behavior.
  • minCount (unsigned int): Minimum number of SMs required

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION

See also

muDevResourceGenerateDesc​

MUresult muDevResourceGenerateDesc(MUdevResourceDesc *phDesc, MUdevResource *resources, unsigned int nbResources)

Description

  • Splits a MU_DEV_RESOURCE_TYPE_SM resource into structured groups.
  • This API will split a resource of MU_DEV_RESOURCE_TYPE_SM into nbGroups structured device resource groups (the result array), as well as an optional remainder, according to a set of requirements specified in the groupParams array. The term “structured” is a trait that specifies the result has SMs that are co-scheduled together. This co-scheduling can be specified via the coscheduledSmCount field of the groupParams structure, while the smCount will specify how many SMs are required in total for that result. The remainder is always “unstructured”, it does not have any set guarantees with respect to co-scheduling and those properties will need to either be queried via the occupancy set of APIs or further split into structured groups by this API.
  • The API has a discovery mode for use cases where it is difficult to know ahead of time what the SM count should be. Discovery happens when the smCount field of a given groupParams array entry is set to 0 - the smCount will be filled in by the API with the derived SM count according to the provided groupParams fields and constraints. Discovery can be used with both a valid result array and with a NULL result pointer value. The latter is useful in situations where the smCount will end up being zero, which is an invalid value to create a result entry with, but allowed for discovery purposes when the result is NULL.
  • The groupParams array is evaluated from index 0 to nbGroups - 1. For each index in the groupParams array, the API will evaluate which SMs may be a good fit based on constraints and assign those SMs to result. This evaluation order is important to consider when using discovery mode, as it helps discover the remaining SMs.
  • For a valid call: result should point to a MUdevResource array of size nbGroups, or alternatively, may be NULL, if the developer wishes for only the groupParams entries to be updated input should be a valid MU_DEV_RESOURCE_TYPE_SM resource that originates from querying the green context, device context, or device. The remainder group may be NULL. There are no API flags at this time, so the value passed in should be 0. A MU_DEV_SM_RESOURCE_GROUP_PARAMS array of size nbGroups. Each entry must be zero-initialized. smCount: must be either 0 or in the range of [2,inputSmCount] where inputSmCount is the amount of SMs the input resource has. smCount must be a multiple of 2, as well as a multiple of coscheduledSmCount. When assigning SMs to a group (and if results are expected by having the result parameter set), smCount cannot end up with 0 or a value less than coscheduledSmCount otherwise MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION will be returned. coscheduledSmCount: allows grouping SMs together in order to be able to launch clusters on Compute Architecture 9.0+. The default value may be queried from the device’s MU_DEV_RESOURCE_TYPE_SM resource (8 on Compute Architecture 9.0+ and 2 otherwise). The maximum is 32 on Compute Architecture 9.0+ and 2 otherwise. preferredCoscheduledSmCount: Attempts to merge coscheduledSmCount groups into larger groups, in order to make use of preferredClusterDimensions on Compute Architecture 10.0+. The default value is set to coscheduledSmCount. flags: MU_DEV_SM_RESOURCE_GROUP_BACKFILL: lets smCount be a non-multiple of coscheduledSmCount, filling the difference between SM count and already assigned co-scheduled groupings with other SMs. This lets any resulting group behave similar to the remainder group for example.
  • Example params and their effect:
  • A groupParams array element is defined in the following order: {.smCount,.coscheduledSmCount,.preferredCoscheduledSmCount,.flags,/*.reserved*/}
  • //Example1 //WilldiscoverhowmanySMsthereare,thatareco-scheduledingroupsofsmCoscheduledAlignment. //Therestisplacedintheoptionalremainder. MU_DEV_SM_RESOURCE_GROUP_PARAMSparams{0,0,0,0}; //Example2 //Assumingthedevicehas10+SMs,theresultwillhave10SMsthatareco-scheduledingroupsof2SMs. //Therestisplacedintheoptionalremainder. MU_DEV_SM_RESOURCE_GROUP_PARAMSparams{10,2,0,0}; //SettingthecoscheduledSmCountto2guaranteesthatwecanalwayshaveavalidresult //aslongastheSMcountislessthanorequaltotheinputresourceSMcount. //Example3 //Asinglepieceissplit-off,butinsteadofassigningtheresttotheremainder,asecondgroupcontainseverythingelse //Thisassumesthedevicehas10+SMs(8ofwhicharecoscheduledingroupsof4), //otherwisethesecondgroupcouldendupwith0SMs,whichisnotallowed. MU_DEV_SM_RESOURCE_GROUP_PARAMSparams{{8,4,0,0},{0,2,0,MU_DEV_SM_RESOURCE_GROUP_BACKFILL}}
  • The difference between a catch-all param group as the last entry and the remainder is in two aspects: The remainder may be NULL / _TYPE_INVALID (if there are no SMs remaining), while a result group must always be valid. The remainder does not have a structure, while the result group will always need to adhere to a structure of coscheduledSmCount (even if its just 2), and therefore must always have enough coscheduled SMs to cover that requirement (even with the MU_DEV_SM_RESOURCE_GROUP_BACKFILL flag enabled).
  • Splitting an input into N groups, can be accomplished by repeatedly splitting off 1 group and re-splitting the remainder (a bisect operation). However, it's recommended to accomplish this with a single call wherever possible.
  • Generates a single resource descriptor with the set of resources specified in resources. The generated resource descriptor is necessary for the creation of green contexts via the muGreenCtxCreate API. Resources of the same type can be passed in, provided they meet the requirements as noted below.
  • A successful API call must have: A valid output pointer for the phDesc descriptor as well as a valid array of resources pointers, with the array size passed in nbResources. If multiple resources are provided in resources, the device they came from must be the same, otherwise MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION is returned. If multiple resources are provided in resources and they are of type MU_DEV_RESOURCE_TYPE_SM, they must be outputs (whether result or remaining) from the same split API instance, otherwise MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION is returned.
  • Note: The API is not supported on 32-bit platforms.

Parameters

  • phDesc (MUdevResourceDesc *): Output descriptor
  • resources (MUdevResource *): Array of resources to be included in the descriptor
  • nbResources (unsigned int): Number of resources passed in resources

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_DEVICE, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION
  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_INVALID_RESOURCE_TYPE, MUSA_ERROR_INVALID_RESOURCE_CONFIGURATION

See also

muGreenCtxRecordEvent​

MUresult muGreenCtxRecordEvent(MUgreenCtx hCtx, MUevent hEvent)

Description

  • Records an event.
  • Captures in hEvent all the activities of the green context of hCtx at the time of this call. hEvent and hCtx must be from the same primary context otherwise MUSA_ERROR_INVALID_HANDLE is returned. Calls such as muEventQuery() or muGreenCtxWaitEvent() will then examine or wait for completion of the work that was captured. Uses of hCtx after this call do not modify hEvent.

Parameters

  • hCtx (MUgreenCtx): Green context to record event for
  • hEvent (MUevent): Event to record

Returns

  • MUSA_SUCCESS MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED

Note

  • The API will return MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED if the specified green context hCtx has a stream in the capture mode. In such a case, the call will invalidate all the conflicting captures.

See also

muGreenCtxWaitEvent​

MUresult muGreenCtxWaitEvent(MUgreenCtx hCtx, MUevent hEvent)

Description

  • Make a green context wait on an event.
  • Makes all future work submitted to green context hCtx wait for all work captured in hEvent. The synchronization will be performed on the device and will not block the calling CPU thread. See muGreenCtxRecordEvent() or muEventRecord(), for details on what is captured by an event.

Parameters

  • hCtx (MUgreenCtx): Green context to wait
  • hEvent (MUevent): Event to wait on

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED

Note

  • hEvent may be from a different context or device than hCtx.
  • The API will return MUSA_ERROR_STREAM_CAPTURE_UNSUPPORTED and invalidate the capture if the specified event hEvent is part of an ongoing capture sequence or if the specified green context hCtx has a stream in the capture mode.

See also

muStreamGetGreenCtx​

MUresult muStreamGetGreenCtx(MUstream hStream, MUgreenCtx *phCtx)

Description

  • Query the green context associated with a stream.
  • Returns the MUSA green context that the stream is associated with, or NULL if the stream is not associated with any green context.
  • The stream handle hStream can refer to any of the following: a stream created via any of the MUSA driver APIs such as muStreamCreate, muStreamCreateWithPriority and muGreenCtxStreamCreate, or their runtime API equivalents such as musaStreamCreate, musaStreamCreateWithFlags and musaStreamCreateWithPriority. If during stream creation the context that was active in the calling thread was obtained with muCtxFromGreenCtx, that green context is returned in phCtx. Otherwise, *phCtx is set to NULL instead. special stream such as the NULL stream or MU_STREAM_LEGACY. In that case if context that is active in the calling thread was obtained with muCtxFromGreenCtx, that green context is returned. Otherwise, *phCtx is set to NULL instead. Passing an invalid handle will result in undefined behavior.

Parameters

  • hStream (MUstream): Handle to the stream to be queried
  • phCtx (MUgreenCtx *): Returned green context associated with the stream

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_HANDLE

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muGreenCtxStreamCreate​

MUresult muGreenCtxStreamCreate(MUstream *phStream, MUgreenCtx greenCtx, unsigned int flags, int priority)

Description

  • Create a stream for use in the green context.
  • Creates a stream for use in the specified green context greenCtx and returns a handle in phStream. The stream can be destroyed by calling muStreamDestroy(). Note that the API ignores the context that is current to the calling thread and creates a stream in the specified green context greenCtx.
  • The supported values for flags are: MU_STREAM_NON_BLOCKING: This must be specified. It indicates that work running in the created stream may run concurrently with work in the default stream, and that the created stream should perform no implicit synchronization with the default stream.
  • Specifying priority affects the scheduling priority of work in the stream. Priorities provide a hint to preferentially run work with higher priority when possible, but do not preempt already-running work or provide any other functional guarantee on execution order. priority follows a convention where lower numbers represent higher priorities. '0' represents default priority. The range of meaningful numerical priorities can be queried using muCtxGetStreamPriorityRange. If the specified priority is outside the numerical range returned by muCtxGetStreamPriorityRange, it will automatically be clamped to the lowest or the highest number in the range.

Parameters

  • phStream (MUstream *): Returned newly created stream
  • greenCtx (MUgreenCtx): Green context for which to create the stream for
  • flags (unsigned int): Flags for stream creation. MU_STREAM_NON_BLOCKING must be specified.
  • priority (int): Stream priority. Lower numbers represent higher priorities. See muCtxGetStreamPriorityRange for more information about meaningful stream priorities that can be passed.

Returns

  • MUSA_SUCCESS, MUSA_ERROR_DEINITIALIZED, MUSA_ERROR_NOT_INITIALIZED, MUSA_ERROR_INVALID_CONTEXT, MUSA_ERROR_INVALID_VALUE, MUSA_ERROR_OUT_OF_MEMORY

Note

  • This function may also return error codes from previous, asynchronous launches.
  • In the current implementation, only compute kernels launched in priority streams are affected by the stream's priority. Stream priorities have no effect on host-to-device and device-to-host memory operations.

See also

3.35 Error Log Management​

Information

  • This module is experimental in MUSA SDK 5.2.0 and is provided for reference only.

muLogsRegisterCallback​

MUresult muLogsRegisterCallback(MUlogsCallback callbackFunc, void *userData, MUlogsCallbackHandle *callback_out)

Description

  • Register a callback function to receive error log messages.

Parameters

  • callbackFunc (MUlogsCallback): The function to register as a callback
  • userData (void *): A generic pointer to user data. This is passed into the callback function.
  • callback_out (MUlogsCallbackHandle *): Optional location to store the callback handle after it is registered

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

muLogsUnregisterCallback​

MUresult muLogsUnregisterCallback(MUlogsCallbackHandle callback)

Description

  • Unregister a log message callback.

Parameters

  • callback (MUlogsCallbackHandle): The callback instance to unregister from receiving log messages

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

muLogsCurrent​

MUresult muLogsCurrent(MUlogIterator *iterator_out, unsigned int flags)

Description

  • Sets log iterator to point to the end of log buffer, where the next message would be written.

Parameters

  • iterator_out (MUlogIterator *): Location to store an iterator to the current tail of the logs
  • flags (unsigned int): Reserved for future use, must be 0

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.

muLogsDumpToFile​

MUresult muLogsDumpToFile(MUlogIterator *iterator, const char *pathToFile, unsigned int flags)

Description

  • Dump accumulated driver logs into a file.
  • Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This API dumps all driver logs starting from iterator into pathToFile provided.

Parameters

  • iterator (MUlogIterator *): Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
  • pathToFile (const char *): Path to output file for dumping logs
  • flags (unsigned int): Reserved for future use, must be 0

Returns

  • MUSA_SUCCESS MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • iterator is auto-advancing. Dumping logs will update the value of iterator to receive the next generated log.
  • The driver reserves limited memory for storing logs. The oldest logs may be overwritten and become unrecoverable. An indication will appear in the destination outupt if the logs have been truncated. Call dump after each failed API to mitigate this risk.

muLogsDumpToMemory​

MUresult muLogsDumpToMemory(MUlogIterator *iterator, char *buffer, size_t *size, unsigned int flags)

Description

  • Dump accumulated driver logs into a buffer.
  • Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This API dumps driver logs from iterator into buffer up to the size specified in *size. The driver will always null terminate the buffer but there will not be a null character between log entries, only a newline \n. The driver will then return the actual number of bytes written in *size, excluding the null terminator. If there are no messages to dump, *size will be set to 0 and the function will return MUSA_SUCCESS. If the provided buffer is not large enough to hold any messages, *size will be set to 0 and the function will return MUSA_ERROR_INVALID_VALUE.

Parameters

  • iterator (MUlogIterator *): Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
  • buffer (char *): Pointer to dump logs
  • size (size_t *): See description
  • flags (unsigned int): Reserved for future use, must be 0

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_VALUE

Note

  • This API is provided for reference only in MUSA SDK 5.2.0.
  • Experimental in the current MUSA SDK 5.2.0 delivery scope.
  • iterator is auto-advancing. Dumping logs will update the value of iterator to receive the next generated log.
  • The driver reserves limited memory for storing logs. The maximum size of the buffer is 25600 bytes. The oldest logs may be overwritten and become unrecoverable. An indication will appear in the destination outupt if the logs have been truncated. Call dump after each failed API to mitigate this risk.
  • If the provided value in *size is not large enough to hold all buffered messages, a message will be added at the head of the buffer indicating this. The driver then computes the number of messages it is able to store in buffer and writes it out. The final message in buffer will always be the most recent log message as of when the API is called.

3.36 OpenGL Interoperability​

muGraphicsGLRegisterBuffer​

MUresult muGraphicsGLRegisterBuffer(MUgraphicsResource *pMusaResource, GLuint buffer, unsigned int Flags)

Description

  • Registers an OpenGL buffer object.
  • Registers the buffer object specified by buffer for access by MUSA. A handle to the registered object is returned as pMusaResource. The register flags Flags specify the intended usage, as follows:
  • MU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be used. It is therefore assumed that this resource will be read from and written to by MUSA. This is the default value. MU_GRAPHICS_REGISTER_FLAGS_READ_ONLY: Specifies that MUSA will not write to this resource. MU_GRAPHICS_REGISTER_FLAGS_WRITE_DISCARD: Specifies that MUSA will not read from this resource and will write over the entire contents of the resource, so none of the data previously stored in the resource will be preserved.

Parameters

  • pMusaResource (MUgraphicsResource *): Pointer to the returned object handle
  • buffer (GLuint): name of buffer object to be registered
  • Flags (unsigned int): Register flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ALREADY_MAPPED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muGraphicsGLRegisterImage​

MUresult muGraphicsGLRegisterImage(MUgraphicsResource *pMusaResource, GLuint image, GLenum target, unsigned int Flags)

Description

  • Register an OpenGL texture or renderbuffer object.
  • Registers the texture or renderbuffer object specified by image for access by MUSA. A handle to the registered object is returned as pMusaResource.
  • target must match the type of the object, and must be one of GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE, GL_TEXTURE_CUBE_MAP, GL_TEXTURE_3D, GL_TEXTURE_2D_ARRAY, or GL_RENDERBUFFER.
  • The register flags Flags specify the intended usage, as follows:
  • MU_GRAPHICS_REGISTER_FLAGS_NONE: Specifies no hints about how this resource will be used. It is therefore assumed that this resource will be read from and written to by MUSA. This is the default value. MU_GRAPHICS_REGISTER_FLAGS_READ_ONLY: Specifies that MUSA will not write to this resource. MU_GRAPHICS_REGISTER_FLAGS_WRITE_DISCARD: Specifies that MUSA will not read from this resource and will write over the entire contents of the resource, so none of the data previously stored in the resource will be preserved. MU_GRAPHICS_REGISTER_FLAGS_SURFACE_LDST: Specifies that MUSA will bind this resource to a surface reference. MU_GRAPHICS_REGISTER_FLAGS_TEXTURE_GATHER: Specifies that MUSA will perform texture gather operations on this resource.
  • The following image formats are supported. For brevity's sake, the list is abbreviated. For ex., {GL_R, GL_RG} X {8, 16} would expand to the following 4 formats {GL_R8, GL_R16, GL_RG8, GL_RG16} : GL_RED, GL_RG, GL_RGBA, GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA, GL_INTENSITY {GL_R, GL_RG, GL_RGBA} X {8, 16, 16F, 32F, 8UI, 16UI, 32UI, 8I, 16I, 32I} {GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA, GL_INTENSITY} X {8, 16, 16F_ARB, 32F_ARB, 8UI_EXT, 16UI_EXT, 32UI_EXT, 8I_EXT, 16I_EXT, 32I_EXT}
  • The following image classes are currently disallowed: Textures with borders Multisampled renderbuffers

Parameters

  • pMusaResource (MUgraphicsResource *): Pointer to the returned object handle
  • image (GLuint): name of texture or renderbuffer object to be registered
  • target (GLenum): Identifies the type of object specified by image
  • Flags (unsigned int): Register flags

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_HANDLE, MUSA_ERROR_ALREADY_MAPPED, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

3.37 Profiler Control​

muProfilerStart​

MUresult muProfilerStart(void)

Description

  • Enable profiling.
  • Enables profile collection by the active profiling tool for the current context. If profiling is already enabled, then muProfilerStart() has no effect.
  • muProfilerStart and muProfilerStop APIs are used to programmatically control the profiling granularity by allowing profiling to be done only on selective pieces of code.

Parameters

  • (unnamed) (void)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

muProfilerStop​

MUresult muProfilerStop(void)

Description

  • Disable profiling.
  • Disables profile collection by the active profiling tool for the current context. If profiling is already disabled, then muProfilerStop() has no effect.
  • muProfilerStart and muProfilerStop APIs are used to programmatically control the profiling granularity by allowing profiling to be done only on selective pieces of code.

Parameters

  • (unnamed) (void)

Returns

  • MUSA_SUCCESS, MUSA_ERROR_INVALID_CONTEXT

Note

  • This function may also return error codes from previous, asynchronous launches.

See also

4. Data Types Index​

This section lists public enum, typedef, and macro names for the Driver API. Full structure records are listed under Data Structures.

CategoryName
define__MUSA_API_PTDS
define__MUSA_API_PTSZ
define__MUSA_DEPRECATED
define_CONCAT_INNER
define_CONCAT_OUTER
defineMAX_PLANES
defineMU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL
defineMU_COMPUTE_ACCELERATED_TARGET_BASE
defineMU_COMPUTE_FAMILY_TARGET_BASE
defineMU_DEVICE_CPU
defineMU_DEVICE_INVALID
defineMU_GRAPH_COND_ASSIGN_DEFAULT
defineMU_GRAPH_KERNEL_NODE_PORT_DEFAULT
defineMU_GRAPH_KERNEL_NODE_PORT_LAUNCH_ORDER
defineMU_GRAPH_KERNEL_NODE_PORT_PROGRAMMATIC
defineMU_IPC_HANDLE_SIZE
defineMU_KERNEL_NODE_ATTRIBUTE_ACCESS_POLICY_WINDOW
defineMU_KERNEL_NODE_ATTRIBUTE_CLUSTER_DIMENSION
defineMU_KERNEL_NODE_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE
defineMU_KERNEL_NODE_ATTRIBUTE_COOPERATIVE
defineMU_KERNEL_NODE_ATTRIBUTE_DEVICE_UPDATABLE_KERNEL_NODE
defineMU_KERNEL_NODE_ATTRIBUTE_MEM_SYNC_DOMAIN
defineMU_KERNEL_NODE_ATTRIBUTE_MEM_SYNC_DOMAIN_MAP
defineMU_KERNEL_NODE_ATTRIBUTE_PREFERRED_CLUSTER_DIMENSION
defineMU_KERNEL_NODE_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT
defineMU_KERNEL_NODE_ATTRIBUTE_PRIORITY
defineMU_LAUNCH_KERNEL_REQUIRED_BLOCK_DIM
defineMU_LAUNCH_PARAM_BUFFER_POINTER
defineMU_LAUNCH_PARAM_BUFFER_POINTER_AS_INT
defineMU_LAUNCH_PARAM_BUFFER_SIZE
defineMU_LAUNCH_PARAM_BUFFER_SIZE_AS_INT
defineMU_LAUNCH_PARAM_END
defineMU_LAUNCH_PARAM_END_AS_INT
defineMU_MEM_CREATE_USAGE_HW_DECOMPRESS
defineMU_MEM_CREATE_USAGE_TILE_POOL
defineMU_MEM_POOL_CREATE_USAGE_HW_DECOMPRESS
defineMU_MEMHOSTALLOC_DEVICEMAP
defineMU_MEMHOSTALLOC_PORTABLE
defineMU_MEMHOSTALLOC_WRITECOMBINED
defineMU_MEMHOSTREGISTER_DEVICEMAP
defineMU_MEMHOSTREGISTER_IOMEMORY
defineMU_MEMHOSTREGISTER_PORTABLE
defineMU_MEMHOSTREGISTER_READ_ONLY
defineMU_PARAM_TR_DEFAULT
defineMU_PEERACCESS_BIDIR_INTERLEAVED
defineMU_PEERACCESS_DEFAULT
defineMU_PEERACCESS_HALF_BIDIR_INTERLEAVED
defineMU_PEERACCESS_HETERO_BIDIR_INTERLEAVED
defineMU_PEERACCESS_HETERO_INTERLEAVED
defineMU_PEERACCESS_PCIE_ONLY
defineMU_PEERACCESS_POLICY_MAX
defineMU_PEERACCESS_UNIDIR_INTERLEAVED
defineMU_STREAM_ATTRIBUTE_ACCESS_POLICY_WINDOW
defineMU_STREAM_ATTRIBUTE_MEM_SYNC_DOMAIN
defineMU_STREAM_ATTRIBUTE_MEM_SYNC_DOMAIN_MAP
defineMU_STREAM_ATTRIBUTE_PRIORITY
defineMU_STREAM_ATTRIBUTE_SYNCHRONIZATION_POLICY
defineMU_STREAM_LEGACY
defineMU_STREAM_PER_THREAD
defineMU_TENSOR_DESCRIPTOR_NUM_QWORDS
defineMU_TRSA_OVERRIDE_FORMAT
defineMU_TRSF_DISABLE_TRILINEAR_OPTIMIZATION
defineMU_TRSF_NORMALIZED_COORDINATES
defineMU_TRSF_READ_AS_INTEGER
defineMU_TRSF_SEAMLESS_CUBEMAP
defineMU_TRSF_SRGB
defineMU_UUID_HAS_BEEN_DEFINED
definemuArray3DCreate
definemuArray3DGetDescriptor
definemuArrayCreate
definemuArrayGetDescriptor
definemuCtxCreate
definemuCtxCreate_v3
definemuCtxCreate_v4
definemuCtxDestroy
definemuCtxPopCurrent
definemuCtxPushCurrent
definemuDeviceGetUuid_v2
definemuDevicePrimaryCtxRelease
definemuDevicePrimaryCtxReset
definemuDevicePrimaryCtxSetFlags
definemuDeviceTotalMem
definemuEventDestroy
definemuGetProcAddress
definemuGLCtxCreate
definemuGLGetDevices
definemuGLMapBufferObject
definemuGLMapBufferObjectAsync
definemuGraphAddKernelNode
definemuGraphExecKernelNodeSetParams
definemuGraphExecUpdate
definemuGraphicsResourceGetMappedPointer
definemuGraphicsResourceSetMapFlags
definemuGraphInstantiate
definemuGraphKernelNodeGetParams
definemuGraphKernelNodeSetParams
definemuIpcOpenMemHandle
definemuLinkAddData
definemuLinkAddFile
definemuLinkCreate
definemuMemAlloc
definemuMemAllocHost
definemuMemAllocPitch
definemuMemBatchDecompressAsync
definemuMemcpy2D
definemuMemcpy2DAsync
definemuMemcpy2DUnaligned
definemuMemcpy3D
definemuMemcpy3DAsync
definemuMemcpy3DBatchAsync
definemuMemcpyAtoA
definemuMemcpyAtoD
definemuMemcpyAtoH
definemuMemcpyAtoHAsync
definemuMemcpyBatchAsync
definemuMemcpyDtoA
definemuMemcpyDtoD
definemuMemcpyDtoDAsync
definemuMemcpyDtoH
definemuMemcpyDtoHAsync
definemuMemcpyHtoA
definemuMemcpyHtoAAsync
definemuMemcpyHtoD
definemuMemcpyHtoDAsync
definemuMemFree
definemuMemGetAddressRange
definemuMemGetInfo
definemuMemHostGetDevicePointer
definemuMemHostRegister
definemuMemsetD16
definemuMemsetD2D16
definemuMemsetD2D32
definemuMemsetD2D8
definemuMemsetD32
definemuMemsetD8
definemuModuleGetGlobal
defineMUSA_ARRAY3D_2DARRAY
defineMUSA_ARRAY3D_COLOR_ATTACHMENT
defineMUSA_ARRAY3D_CUBEMAP
defineMUSA_ARRAY3D_DEFERRED_MAPPING
defineMUSA_ARRAY3D_DEPTH_TEXTURE
defineMUSA_ARRAY3D_LAYERED
defineMUSA_ARRAY3D_SPARSE
defineMUSA_ARRAY3D_SURFACE_LDST
defineMUSA_ARRAY3D_TEXTURE_GATHER
defineMUSA_ARRAY3D_VIDEO_ENCODE_DECODE
defineMUSA_CB
defineMUSA_COOPERATIVE_LAUNCH_MULTI_DEVICE_NO_POST_LAUNCH_SYNC
defineMUSA_COOPERATIVE_LAUNCH_MULTI_DEVICE_NO_PRE_LAUNCH_SYNC
defineMUSA_EGL_INFINITE_TIMEOUT
defineMUSA_EXTERNAL_MEMORY_DEDICATED
defineMUSA_EXTERNAL_SEMAPHORE_SIGNAL_SKIP_MTSCIBUF_MEMSYNC
defineMUSA_EXTERNAL_SEMAPHORE_WAIT_SKIP_MTSCIBUF_MEMSYNC
defineMUSA_MTSCISYNC_ATTR_SIGNAL
defineMUSA_MTSCISYNC_ATTR_WAIT
defineMUSA_VERSION
defineMUSAAPI
definemuStreamBatchMemOp
definemuStreamBeginCapture
definemuStreamDestroy
definemuStreamGetCaptureInfo
definemuStreamGetCaptureInfo_v2
definemuStreamWaitValue32
definemuStreamWaitValue64
definemuStreamWriteValue32
definemuStreamWriteValue64
definemuTexRefGetAddress
definemuTexRefSetAddress
definemuTexRefSetAddress2D
definemuVDPAUCtxCreate
defineRESOURCE_ABI_BYTES
defineRESOURCE_ABI_VERSION
enumcl_context_flags
enumcl_event_flags
enumMUaccessProperty
enumMUaddress_mode
enumMUarray_cubemap_face
enumMUarray_format
enumMUarraySparseSubresourceType
enumMUasyncNotificationType
enumMUatomicOperation
enumMUatomicOperationCapability
enumMUatomicType
enumMUatomicValueType
enumMUcigDataType
enumMUclusterSchedulingPolicy
enumMUcomputemode
enumMUCoredumpGenerationFlags
enumMUcoredumpSettings
enumMUctx_flags
enumMUdevice_attribute
enumMUdevice_P2PAttribute
enumMUdeviceNumaConfig
enumMUdevResourceType
enumMUdevSmResourceGroup_flags
enumMUdevSmResourceSplitByCount_flags
enumMUdevWorkqueueConfigScope
enumMUdirectConvBasicShape
enumMUdirectConvInterleave
enumMUdriverProcAddress_flags
enumMUdriverProcAddressQueryResult
enumMUeglColorFormat
enumMUeglFrameType
enumMUeglResourceLocationFlags
enumMUevent_flags
enumMUevent_record_flags
enumMUevent_sched_flags
enumMUevent_wait_flags
enumMUexecAffinityType
enumMUexternalMemoryHandleType
enumMUexternalSemaphoreHandleType
enumMUfilter_mode
enumMUflushGPUDirectRDMAWritesOptions
enumMUflushGPUDirectRDMAWritesScope
enumMUflushGPUDirectRDMAWritesTarget
enumMUfunc_cache
enumMUfunction_attribute
enumMUfunctionLoadingState
enumMUGLDeviceList
enumMUGLmap_flags
enumMUGPUDirectRDMAWritesOrdering
enumMUgraphChildGraphNodeOwnership
enumMUgraphConditionalNodeType
enumMUgraphDebugDot_flags
enumMUgraphDependencyType
enumMUgraphExecUpdateResult
enumMUgraphicsMapResourceFlags
enumMUgraphicsRegisterFlags
enumMUgraphInstantiate_flags
enumMUgraphInstantiateResult
enumMUgraphMem_attribute
enumMUgraphNodeType
enumMUgreenCtxCreate_flags
enumMUhostTaskSyncMode
enumMUipcMem_flags
enumMUjit_cacheMode
enumMUjit_fallback
enumMUjit_option
enumMUjit_target
enumMUjitInputType
enumMUlaunchAttributeID
enumMUlaunchAttributePortableClusterMode
enumMUlaunchMemSyncDomain
enumMUlibraryOption
enumMUlimit
enumMUlogLevel
enumMUmem_advise
enumMUmem_range_attribute
enumMUmemAccess_flags
enumMUmemAllocationCompType
enumMUmemAllocationGranularity_flags
enumMUmemAllocationHandleType
enumMUmemAllocationType
enumMUmemAttach_flags
enumMUmemcpy3DOperandType
enumMUmemcpyFlags
enumMUmemcpySrcAccessOrder
enumMUmemDecompressAlgorithm
enumMUmemHandleType
enumMUmemLocationType
enumMUmemOperationType
enumMUmemorytype
enumMUmemPool_attribute
enumMUmemRangeFlags
enumMUmemRangeHandleType
enumMUmoduleLoadingMode
enumMUmulticastGranularity_flags
enumMUoccupancy_flags
enumMUoutput_mode
enumMUpointer_attribute
enumMUprocessState
enumMUresourcetype
enumMUresourceViewFormat
enumMUresult
enumMUSA_POINTER_ATTRIBUTE_ACCESS_FLAGS
enumMUshared_carveout
enumMUsharedconfig
enumMUsharedMemoryMode
enumMUstream_flags
enumMUstreamAtomicReductionDataType
enumMUstreamAtomicReductionOpType
enumMUstreamBatchMemOpType
enumMUstreamCaptureMode
enumMUstreamCaptureStatus
enumMUstreamCigDataType
enumMUstreamMemoryBarrier_flags
enumMUstreamUpdateCaptureDependencies_flags
enumMUstreamWaitValue_flags
enumMUstreamWriteValue_flags
enumMUsynchronizationPolicy
enumMUtensorDescriptorDataType
enumMUtensorDescriptorInterleave
enumMUuserObject_flags
enumMUuserObjectRetain_flags
typedefMUaccessPolicyWindow
typedefMUarray
typedefMUarrayMapInfo
typedefMUasyncCallback
typedefMUasyncCallbackHandle
typedefMUcontext
typedefMUcoredumpCallbackHandle
typedefMUdevice
typedefMUdevice_v1
typedefMUdeviceptr
typedefMUdeviceptr_v2
typedefMUdevprop
typedefMUdevResourceDesc
typedefMUeglStreamConnection
typedefMUevent
typedefMUexecAffinityParam
typedefMUexecAffinitySmCount
typedefMUextent3D
typedefMUexternalMemory
typedefMUexternalSemaphore
typedefMUfunction
typedefMUgraph
typedefMUgraphConditionalHandle
typedefMUgraphDeviceNode
typedefMUgraphExec
typedefMUgraphExecUpdateResultInfo
typedefMUgraphicsResource
typedefMUgraphNode
typedefMUgreenCtx
typedefMUhostFn
typedefMUipcEventHandle
typedefMUipcMemHandle
typedefMUkernel
typedefMUkernelNodeAttrID
typedefMUkernelNodeAttrValue
typedefMUkernelNodeAttrValue_v1
typedefMUlibrary
typedefMUlinkState
typedefMUlogIterator
typedefMUlogsCallback
typedefMUlogsCallbackHandle
typedefMUmemAccessDesc
typedefMUmemAllocationProp
typedefMUmemcpy3DOperand
typedefMUmemcpyAttributes
typedefMUmemFabricHandle
typedefMUmemGenericAllocationHandle
typedefMUmemGenericAllocationHandle_v1
typedefMUmemLocation
typedefMUmemoryPool
typedefMUmemPoolProps
typedefMUmemPoolPtrExportData
typedefMUmipmappedArray
typedefMUmodule
typedefMUmulticastObjectProp
typedefMUoccupancyB2DSize
typedefMUoffset3D
typedefMUSA_ARRAY3D_DESCRIPTOR
typedefMUSA_ARRAY_DESCRIPTOR
typedefMUSA_ARRAY_MEMORY_REQUIREMENTS
typedefMUSA_ARRAY_SPARSE_PROPERTIES
typedefMUSA_BATCH_MEM_OP_NODE_PARAMS
typedefMUSA_EXT_SEM_SIGNAL_NODE_PARAMS
typedefMUSA_EXT_SEM_WAIT_NODE_PARAMS
typedefMUSA_EXTERNAL_MEMORY_BUFFER_DESC
typedefMUSA_EXTERNAL_MEMORY_HANDLE_DESC
typedefMUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC
typedefMUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC
typedefMUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS
typedefMUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS
typedefMUSA_HOST_NODE_PARAMS
typedefMUSA_KERNEL_NODE_PARAMS
typedefMUSA_LAUNCH_PARAMS
typedefMUSA_MEM_ALLOC_NODE_PARAMS
typedefMUSA_MEM_ATOMIC_NODE_PARAMS
typedefMUSA_MEM_ATOMIC_VALUE_NODE_PARAMS
typedefMUSA_MEM_TRANSFER_NODE_PARAMS
typedefMUSA_MEM_WAIT_WRITE_NODE_PARAMS
typedefMUSA_MEMCPY2D
typedefMUSA_MEMCPY3D
typedefMUSA_MEMCPY3D_BATCH_OP
typedefMUSA_MEMCPY3D_PEER
typedefMUSA_MEMSET_NODE_PARAMS
typedefMUSA_POINTER_ATTRIBUTE_P2P_TOKENS
typedefMUSA_RESOURCE_DESC
typedefMUSA_RESOURCE_VIEW_DESC
typedefMUSA_TEXTURE_DESC
typedefMUstream
typedefMUstreamAttrID
typedefMUstreamAttrValue
typedefMUstreamAttrValue_v1
typedefMUstreamBatchMemOpParams
typedefMUstreamCallback
typedefMUsurfObject
typedefMUsurfObject_v1
typedefMUsurfref
typedefMUtexObject
typedefMUtexObject_v1
typedefMUtexref
typedefmuuint32_t
typedefmuuint64_t
typedefMUuserObject

5. Data Structures​

This section lists public structures and unions for the Driver API.

CategoryName
StructsMU_DEV_SM_RESOURCE_GROUP_PARAMS
StructsMUaccessPolicyWindow_v1
StructsMUarrayMapInfo_v1
StructsMUasyncNotificationInfo
StructsMUcheckpointCheckpointArgs
StructsMUcheckpointGpuPair
StructsMUcheckpointLockArgs
StructsMUcheckpointRestoreArgs
StructsMUcheckpointUnlockArgs
StructsMUconvParamer
StructsMUctxCigParam
StructsMUctxCreateParams
StructsMUdevprop_v1
StructsMUdevResource
StructsMUdevResource_st
StructsMUdevSmResource
StructsMUdevWorkqueueConfigResource
StructsMUdevWorkqueueResource
StructsMUdirectConvParamer
StructsMUeglFrame
StructsMUexecAffinityParam_v1
StructsMUexecAffinitySmCount_v1
StructsMUextent3D_v1
StructsMUgraphEdgeData
StructsMUgraphExecUpdateResultInfo_v1
StructsMUgraphNodeParams
StructsMUipcEventHandle_v1
StructsMUipcMemHandle_v1
StructsMUlaunchAttribute
StructsMUlaunchConfig
StructsMUlaunchMemSyncDomainMap
StructsMUlibraryHostUniversalFunctionAndDataTable
StructsMUmemAccessDesc_v1
StructsMUmemAllocationProp_v1
StructsMUmemcpy3DOperand_v1
StructsMUmemcpyAttributes_v1
StructsMUmemDecompressParams
StructsMUmemFabricHandle_v1
StructsMUmemLocation_v1
StructsMUmemPoolProps_v1
StructsMUmemPoolPtrExportData_v1
StructsMUmulticastObjectProp_v1
StructsMUoffset3D_v1
StructsMUSA_ARRAY3D_DESCRIPTOR_v2
StructsMUSA_ARRAY_DESCRIPTOR_v2
StructsMUSA_ARRAY_MEMORY_REQUIREMENTS_v1
StructsMUSA_ARRAY_SPARSE_PROPERTIES_v1
StructsMUSA_BATCH_MEM_OP_NODE_PARAMS_v1
StructsMUSA_BATCH_MEM_OP_NODE_PARAMS_v2
StructsMUSA_CHILD_GRAPH_NODE_PARAMS
StructsMUSA_CONDITIONAL_NODE_PARAMS
StructsMUSA_EVENT_RECORD_NODE_PARAMS
StructsMUSA_EVENT_WAIT_NODE_PARAMS
StructsMUSA_EXT_SEM_SIGNAL_NODE_PARAMS_v1
StructsMUSA_EXT_SEM_SIGNAL_NODE_PARAMS_v2
StructsMUSA_EXT_SEM_WAIT_NODE_PARAMS_v1
StructsMUSA_EXT_SEM_WAIT_NODE_PARAMS_v2
StructsMUSA_EXTERNAL_MEMORY_BUFFER_DESC_v1
StructsMUSA_EXTERNAL_MEMORY_HANDLE_DESC_v1
StructsMUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC_v1
StructsMUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC_v1
StructsMUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1
StructsMUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1
StructsMUSA_GRAPH_INSTANTIATE_PARAMS
StructsMUSA_HOST_NODE_PARAMS_v1
StructsMUSA_HOST_NODE_PARAMS_v2
StructsMUSA_KERNEL_NODE_PARAMS_v1
StructsMUSA_KERNEL_NODE_PARAMS_v2
StructsMUSA_KERNEL_NODE_PARAMS_v3
StructsMUSA_LAUNCH_PARAMS_v1
StructsMUSA_MEM_ALLOC_NODE_PARAMS_v1
StructsMUSA_MEM_ALLOC_NODE_PARAMS_v2
StructsMUSA_MEM_ATOMIC_NODE_PARAMS_v1
StructsMUSA_MEM_ATOMIC_VALUE_NODE_PARAMS_v1
StructsMUSA_MEM_FREE_NODE_PARAMS
StructsMUSA_MEM_TRANSFER_NODE_PARAMS_v1
StructsMUSA_MEM_WAIT_WRITE_NODE_PARAMS_v1
StructsMUSA_MEMCPY2D_v2
StructsMUSA_MEMCPY3D_BATCH_OP_v1
StructsMUSA_MEMCPY3D_PEER_v1
StructsMUSA_MEMCPY3D_v2
StructsMUSA_MEMCPY_NODE_PARAMS
StructsMUSA_MEMSET_NODE_PARAMS_v1
StructsMUSA_MEMSET_NODE_PARAMS_v2
StructsMUSA_POINTER_ATTRIBUTE_P2P_TOKENS_v1
StructsMUSA_RESOURCE_DESC_v1
StructsMUSA_RESOURCE_VIEW_DESC_v1
StructsMUSA_TEXTURE_DESC_v1
StructsMUstreamBatchMemOpParams_v1::MUstreamMemOpAtomicReductionParams_st
StructsMUstreamBatchMemOpParams_v1::MUstreamMemOpFlushRemoteWritesParams_st
StructsMUstreamBatchMemOpParams_v1::MUstreamMemOpMemoryBarrierParams_st
StructsMUstreamBatchMemOpParams_v1::MUstreamMemOpWaitValueParams_st
StructsMUstreamBatchMemOpParams_v1::MUstreamMemOpWriteValueParams_st
StructsMUstreamCigCaptureParams
StructsMUstreamCigParam
StructsMUtensorDescriptor
StructsMUuuid
UnionsMUlaunchAttributeValue
UnionsMUstreamBatchMemOpParams_v1

6. Data Fields​

This section groups public fields by Driver API structure or union. Expand a structure to view its fields.

MU_DEV_SM_RESOURCE_GROUP_PARAMS (5 fields)
FieldTypeDescription
coscheduledSmCountunsigned intThe amount of co-scheduled SMs grouped together for locality purposes.
flagsunsigned intThe flags set on this SM resource group. For possible values see MUdevSmResourceGroup_flags.
preferredCoscheduledSmCountunsigned intWhen possible, combine co-scheduled groups together into larger groups of this size.
reservedunsigned int
smCountunsigned intThe amount of SMs available in this resource.
MUaccessPolicyWindow_v1 (5 fields)
FieldTypeDescription
base_ptrvoid *Starting address of the access policy window. MUSA driver may align it.
hitPropMUaccessPropertyMUaccessProperty set for hit.
hitRatiofloathitRatio specifies percentage of lines assigned hitProp, rest are assigned missProp.
missPropMUaccessPropertyMUaccessProperty set for miss. Must be either NORMAL or STREAMING
num_bytessize_tSize in bytes of the window policy. MUSA driver may restrict the maximum size and alignment.
MUarrayMapInfo_v1 (25 fields)
FieldTypeDescription
arrayMUarray
deviceBitMaskunsigned intDevice ordinal bit mask
extentDepthunsigned intDepth in elements
extentHeightunsigned intHeight in elements
extentWidthunsigned intWidth in elements
flagsunsigned intflags for future use, must be zero now.
layerunsigned intFor MUSA layered arrays must be a valid layer index. Otherwise, must be zero
levelunsigned intFor MUSA mipmapped arrays must a valid mipmap level. For MUSA arrays must be zero
memHandleMUmemGenericAllocationHandle
memHandleunion MUarrayMapInfo_v1::@33
memHandleTypeMUmemHandleTypeMemory handle type
memOperationTypeMUmemOperationTypeMemory operation type
mipmapMUmipmappedArray
miptailstruct MUarrayMapInfo_v1::@32::@35
offsetunsigned long longOffset within mip tail Offset within the memory
offsetXunsigned intStarting X offset in elements
offsetYunsigned intStarting Y offset in elements
offsetZunsigned intStarting Z offset in elements
reservedunsigned intReserved for future use, must be zero now.
resourceunion MUarrayMapInfo_v1::@31
resourceTypeMUresourcetypeResource type
sizeunsigned long longExtent in bytes
sparseLevelstruct MUarrayMapInfo_v1::@32::@34
subresourceunion MUarrayMapInfo_v1::@32
subresourceTypeMUarraySparseSubresourceTypeSparse subresource type
MUasyncNotificationInfo (4 fields)
FieldTypeDescription
bytesOverBudgetunsigned long long
infounion MUasyncNotificationInfo::@4
overBudgetstruct MUasyncNotificationInfo::@4::@5
typeMUasyncNotificationType
MUcheckpointCheckpointArgs (1 field)
FieldTypeDescription
reservedmuuint64_tReserved for future use, must be zeroed
MUcheckpointGpuPair (2 fields)
FieldTypeDescription
newUuidMUuuidUUID of the GPU to restore onto
oldUuidMUuuidUUID of the GPU that was checkpointed
MUcheckpointLockArgs (3 fields)
FieldTypeDescription
reserved0unsigned intReserved for future use, must be zero
reserved1muuint64_tReserved for future use, must be zeroed
timeoutMsunsigned intTimeout in milliseconds to attempt to lock the process, 0 indicates no timeout
MUcheckpointRestoreArgs (4 fields)
FieldTypeDescription
gpuPairsMUcheckpointGpuPair *Pointer to array of gpu pairs that indicate how to remap GPUs during restore
gpuPairsCountunsigned intNumber of gpu pairs to remap
reservedcharReserved for future use, must be zeroed
reserved1muuint64_tReserved for future use, must be zeroed
MUcheckpointUnlockArgs (1 field)
FieldTypeDescription
reservedmuuint64_tReserved for future use, must be zeroed
MUconvParamer (1 field)
FieldTypeDescription
paramsint
MUctxCigParam (2 fields)
FieldTypeDescription
sharedDatavoid *
sharedDataTypeMUcigDataType
MUctxCreateParams (3 fields)
FieldTypeDescription
cigParamsMUctxCigParam *
execAffinityParamsMUexecAffinityParam *
numExecAffinityParamsint
MUdevprop_v1 (10 fields)
FieldTypeDescription
clockRateintClock frequency in kilohertz
maxGridSizeintMaximum size of each dimension of a grid
maxThreadsDimintMaximum size of each dimension of a block
maxThreadsPerBlockintMaximum number of threads per block
memPitchintMaximum pitch in bytes allowed by memory copies
regsPerBlockint32-bit registers available per block
sharedMemPerBlockintShared memory available per block in bytes
SIMDWidthintWarp size in threads
textureAlignintAlignment requirement for textures
totalConstantMemoryintConstant memory available on device in bytes
MUdevResource_st (8 fields)
FieldTypeDescription
@43union MUdevResource_st::@42
_internal_paddingunsigned char
_oversizeunsigned char
nextResourcestruct MUdevResource_st *
smMUdevSmResourceResource corresponding to MU_DEV_RESOURCE_TYPE_SM . type.
typeMUdevResourceTypeType of resource, dictates which union field was last set
wqMUdevWorkqueueResourceResource corresponding to MU_DEV_RESOURCE_TYPE_WORKQUEUE type.
wqConfigMUdevWorkqueueConfigResourceResource corresponding to MU_DEV_RESOURCE_TYPE_WORKQUEUE_CONFIG type.
MUdevSmResource (4 fields)
FieldTypeDescription
flagsunsigned intThe flags set on this SM resource. For possible values see MUdevSmResourceGroup_flags.
minSmPartitionSizeunsigned intThe minimum number of streaming multiprocessors required to partition this resource.
smCoscheduledAlignmentunsigned intThe number of streaming multiprocessors in this resource that are guaranteed to be co-scheduled on the same GPU processing cluster. smCount will be a multiple of this value, unless the backfill flag is set.
smCountunsigned intThe amount of streaming multiprocessors available in this resource. This is an output parameter only, do not write to this field.
MUdevWorkqueueConfigResource (3 fields)
FieldTypeDescription
deviceMUdeviceThe device on which the workqueue resources are available
sharingScopeMUdevWorkqueueConfigScopeThe sharing scope for the workqueue resources
wqConcurrencyLimitunsigned intThe expected maximum number of concurrent stream-ordered workloads
MUdevWorkqueueResource (1 field)
FieldTypeDescription
reservedunsigned charReserved for future use
MUdirectConvParamer (1 field)
FieldTypeDescription
byteschar
MUeglFrame (12 fields)
FieldTypeDescription
depthunsigned intDepth of first plane
eglColorFormatMUeglColorFormatMUSA EGL Color Format
frameunion MUeglFrame::@46
frameTypeMUeglFrameTypeArray or Pitch
heightunsigned intHeight of first plane
muFormatMUarray_formatMUSA Array Format
numChannelsunsigned intNumber of channels for the plane
pArrayMUarrayArray of MUarray corresponding to each plane
pitchunsigned intPitch of first plane
planeCountunsigned intNumber of planes
pPitchvoid *Array of Pointers corresponding to each plane
widthunsigned intWidth of first plane
MUexecAffinityParam_v1 (3 fields)
FieldTypeDescription
paramunion MUexecAffinityParam_v1::@11
smCountMUexecAffinitySmCount
typeMUexecAffinityType
MUexecAffinitySmCount_v1 (1 field)
FieldTypeDescription
valunsigned intThe number of SMs the context is limited to use.
MUextent3D_v1 (3 fields)
FieldTypeDescription
depthsize_t
heightsize_t
widthsize_t
MUgraphEdgeData (4 fields)
FieldTypeDescription
from_portunsigned charThis indicates when the dependency is triggered from the upstream node on the edge. The meaning is specfic to the node type. A value of 0 in all cases means full completion of the upstream node, with memory visibility to the downstream node or portion thereof (indicated by to_port). Only kernel nodes define non-zero ports. A kernel node can use the following output port types: MU_GRAPH_KERNEL_NODE_PORT_DEFAULT, MU_GRAPH_KERNEL_NODE_PORT_PROGRAMMATIC, or MU_GRAPH_KERNEL_NODE_PORT_LAUNCH_ORDER.
reservedunsigned charThese bytes are unused and must be zeroed. This ensures compatibility if additional fields are added in the future.
to_portunsigned charThis indicates what portion of the downstream node is dependent on the upstream node or portion thereof (indicated by from_port). The meaning is specific to the node type. A value of 0 in all cases means the entirety of the downstream node is dependent on the upstream work. Currently no node types define non-zero ports. Accordingly, this field must be set to zero.
typeunsigned charThis should be populated with a value from MUgraphDependencyType. (It is typed as char due to compiler-specific layout of bitfields.) See MUgraphDependencyType.
MUgraphExecUpdateResultInfo_v1 (3 fields)
FieldTypeDescription
errorFromNodeMUgraphNodeThe from node of error edge when the topologies do not match. Otherwise NULL.
errorNodeMUgraphNodeThe "to node" of the error edge when the topologies do not match. The error node when the error is associated with a specific node. NULL when the error is generic.
resultMUgraphExecUpdateResultGives more specific detail when a musa graph update fails.
MUgraphNodeParams (18 fields)
FieldTypeDescription
@38union MUgraphNodeParams::@37
allocMUSA_MEM_ALLOC_NODE_PARAMS_v2Memory allocation node parameters.
conditionalMUSA_CONDITIONAL_NODE_PARAMSConditional node parameters.
eventRecordMUSA_EVENT_RECORD_NODE_PARAMSEvent record node parameters.
eventWaitMUSA_EVENT_WAIT_NODE_PARAMSEvent wait node parameters.
extSemSignalMUSA_EXT_SEM_SIGNAL_NODE_PARAMS_v2External semaphore signal node parameters.
extSemWaitMUSA_EXT_SEM_WAIT_NODE_PARAMS_v2External semaphore wait node parameters.
freeMUSA_MEM_FREE_NODE_PARAMSMemory free node parameters.
graphMUSA_CHILD_GRAPH_NODE_PARAMSChild graph node parameters.
hostMUSA_HOST_NODE_PARAMS_v2Host node parameters.
kernelMUSA_KERNEL_NODE_PARAMS_v3Kernel node parameters.
memcpyMUSA_MEMCPY_NODE_PARAMSMemcpy node parameters.
memOpMUSA_BATCH_MEM_OP_NODE_PARAMS_v2MemOp node parameters.
memsetMUSA_MEMSET_NODE_PARAMS_v2Memset node parameters.
reserved0intReserved. Must be zero.
reserved1long longPadding. Unused bytes must be zero.
reserved2long longReserved bytes. Must be zero.
typeMUgraphNodeTypeType of the node
MUipcEventHandle_v1 (1 field)
FieldTypeDescription
reservedchar
MUipcMemHandle_v1 (1 field)
FieldTypeDescription
reservedchar
MUlaunchAttribute (3 fields)
FieldTypeDescription
idMUlaunchAttributeIDAttribute to set
padchar
valueMUlaunchAttributeValueValue of the attribute
MUlaunchAttributeValue (26 fields)
FieldTypeDescription
accessPolicyWindowMUaccessPolicyWindowValue of launch attribute MU_LAUNCH_ATTRIBUTE_ACCESS_POLICY_WINDOW.
clusterDimstruct MUlaunchAttributeValue::@6Value of launch attribute MU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION that represents the desired cluster dimensions for the kernel. Opaque type with the following fields:
clusterSchedulingPolicyPreferenceMUclusterSchedulingPolicyValue of launch attribute MU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE. Cluster scheduling policy preference for the kernel.
cooperativeintValue of launch attribute MU_LAUNCH_ATTRIBUTE_COOPERATIVE. Nonzero indicates a cooperative kernel (see muLaunchCooperativeKernel).
deviceUpdatableint
deviceUpdatableKernelNodestruct MUlaunchAttributeValue::@10Value of launch attribute MU_LAUNCH_ATTRIBUTE_DEVICE_UPDATABLE_KERNEL_NODE. with the following fields:
devNodeMUgraphDeviceNode
eventMUevent
flagsint
launchCompletionEventstruct MUlaunchAttributeValue::@8Value of launch attribute MU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT with the following fields:
memSyncDomainMUlaunchMemSyncDomainValue of launch attribute MU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN. See::MUlaunchMemSyncDomain
memSyncDomainMapMUlaunchMemSyncDomainMapValue of launch attribute MU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN_MAP. See MUlaunchMemSyncDomainMap.
mtlinkUtilCentricSchedulingunsigned int
padchar
portableClusterSizeModeMUlaunchAttributePortableClusterModeValue of launch attribute MU_LAUNCH_ATTRIBUTE_PORTABLE_CLUSTER_SIZE_MODE.
preferredClusterDimstruct MUlaunchAttributeValue::@9Value of launch attribute MU_LAUNCH_ATTRIBUTE_PREFERRED_CLUSTER_DIMENSION that represents the desired preferred cluster dimensions for the kernel. Opaque type with the following fields:
priorityintValue of launch attribute MU_LAUNCH_ATTRIBUTE_PRIORITY. Execution priority of the kernel.
programmaticEventstruct MUlaunchAttributeValue::@7Value of launch attribute MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_EVENT with the following fields:
programmaticStreamSerializationAllowedintValue of launch attribute MU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_STREAM_SERIALIZATION.
sharedMemCarveoutunsigned intValue of launch attribute MU_LAUNCH_ATTRIBUTE_PREFERRED_SHARED_MEMORY_CARVEOUT.
sharedMemoryModeMUsharedMemoryModeValue of launch attribute MU_LAUNCH_ATTRIBUTE_SHARED_MEMORY_MODE. See MUsharedMemoryMode for acceptable values.
syncPolicyMUsynchronizationPolicyValue of launch attribute MU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY. MUsynchronizationPolicy for work queued up in this stream
triggerAtBlockStartint
xunsigned int
yunsigned int
zunsigned int
MUlaunchConfig (10 fields)
FieldTypeDescription
attrsMUlaunchAttribute *List of attributes; nullable if MUlaunchConfig::numAttrs == 0
blockDimXunsigned intX dimension of each thread block
blockDimYunsigned intY dimension of each thread block
blockDimZunsigned intZ dimension of each thread block
gridDimXunsigned intWidth of grid in blocks
gridDimYunsigned intHeight of grid in blocks
gridDimZunsigned intDepth of grid in blocks
hStreamMUstreamStream identifier
numAttrsunsigned intNumber of attributes populated in MUlaunchConfig::attrs
sharedMemBytesunsigned intDynamic shared-memory size per thread block in bytes
MUlaunchMemSyncDomainMap (2 fields)
FieldTypeDescription
default_unsigned charThe default domain ID to use for designated kernels
remoteunsigned charThe remote domain ID to use for designated kernels
MUlibraryHostUniversalFunctionAndDataTable (4 fields)
FieldTypeDescription
dataTablevoid *
dataWindowSizesize_t
functionTablevoid *
functionWindowSizesize_t
MUmemAccessDesc_v1 (2 fields)
FieldTypeDescription
flagsMUmemAccess_flagsMUmemProt accessibility flags to set on the request
locationMUmemLocationLocation on which the request is to change it's accessibility
MUmemAllocationProp_v1 (9 fields)
FieldTypeDescription
allocFlagsstruct MUmemAllocationProp_v1::@36
compressionTypeunsigned charAllocation hint for requesting compressible memory. On devices that support Compute Data Compression, compressible memory can be used to accelerate accesses to data with unstructured sparsity and other compressible data patterns. Applications are expected to query allocation property of the handle obtained with muMemCreate using muMemGetAllocationPropertiesFromHandle to validate if the obtained allocation is compressible or not. Note that compressed memory may not be mappable on all devices.
gpuDirectRDMACapableunsigned char
locationMUmemLocationLocation of allocation
requestedHandleTypesMUmemAllocationHandleTyperequested MUmemAllocationHandleType
reservedunsigned char
typeMUmemAllocationTypeAllocation type
usageunsigned shortBitmask indicating intended usage for this allocation
win32HandleMetaDatavoid *Windows-specific POBJECT_ATTRIBUTES required when MU_MEM_HANDLE_TYPE_WIN32 is specified. This object attributes structure includes security attributes that define the scope of which exported allocations may be transferred to other processes. In all other cases, this field is required to be zero.
MUmemcpy3DOperand_v1 (10 fields)
FieldTypeDescription
arrayMUarray
arraystruct MUmemcpy3DOperand_v1::@39::@41Struct representing an operand when MUmemcpy3DOperand::type is MU_MEMCPY_OPERAND_TYPE_ARRAY
layerHeightsize_tHeight of each layer in elements.
locHintMUmemLocationHint location for the operand. Ignored when the pointers are not managed memory or memory allocated outside MUSA.
offsetMUoffset3D
opunion MUmemcpy3DOperand_v1::@39
ptrMUdeviceptr
ptrstruct MUmemcpy3DOperand_v1::@39::@40Struct representing an operand when MUmemcpy3DOperand::type is MU_MEMCPY_OPERAND_TYPE_POINTER
rowLengthsize_tLength of each row in elements.
typeMUmemcpy3DOperandType
MUmemcpyAttributes_v1 (4 fields)
FieldTypeDescription
dstLocHintMUmemLocationHint location for the destination operand. Ignored when the pointers are not managed memory or memory allocated outside MUSA.
flagsunsigned intAdditional flags for copies with this attribute. See MUmemcpyFlags
srcAccessOrderMUmemcpySrcAccessOrderSource access ordering to be observed for copies with this attribute.
srcLocHintMUmemLocationHint location for the source operand. Ignored when the pointers are not managed memory or memory allocated outside MUSA.
MUmemDecompressParams (7 fields)
FieldTypeDescription
algoMUmemDecompressAlgorithmThe decompression algorithm to use.
dstvoid *Pointer to a buffer where the decompressed data will be written. The number of bytes written to this location will be recorded in the memory pointed to by MUmemDecompressParams_st.dstActBytes
dstActBytesmuuint32_t *After the decompression operation has completed, the actual number of bytes written to MUmemDecompressParams.dst will be recorded as a 32-bit unsigned integer in the memory at this address.
dstNumBytessize_tThe number of bytes that the decompression operation will be expected to write to MUmemDecompressParams_st.dst. This value is optional; if present, it may be used by the MUSA driver as a heuristic for scheduling the individual decompression operations.
paddingunsigned char
srcconst void *Pointer to a buffer of at least MUmemDecompressParams_st.srcNumBytes compressed bytes.
srcNumBytessize_tThe number of bytes to be read and decompressed from MUmemDecompressParams_st.src.
MUmemFabricHandle_v1 (1 field)
FieldTypeDescription
dataunsigned char
MUmemLocation_v1 (2 fields)
FieldTypeDescription
idintidentifier for a given this location's MUmemLocationType.
typeMUmemLocationTypeSpecifies the location type, which modifies the meaning of id.
MUmemPoolProps_v1 (7 fields)
FieldTypeDescription
allocTypeMUmemAllocationTypeAllocation type. Currently must be specified as MU_MEM_ALLOCATION_TYPE_PINNED
handleTypesMUmemAllocationHandleTypeHandle types that will be supported by allocations from the pool.
locationMUmemLocationLocation where allocations should reside.
maxSizesize_tMaximum pool size. When set to 0, defaults to a system dependent value.
reservedunsigned charreserved for future use, must be 0
usageunsigned shortBitmask indicating intended usage for the pool.
win32SecurityAttributesvoid *Windows-specific LPSECURITYATTRIBUTES required when MU_MEM_HANDLE_TYPE_WIN32 is specified. This security attribute defines the scope of which exported allocations may be transferred to other processes. In all other cases, this field is required to be zero.
MUmemPoolPtrExportData_v1 (1 field)
FieldTypeDescription
reservedunsigned char
MUmulticastObjectProp_v1 (4 fields)
FieldTypeDescription
flagsunsigned long longFlags for future use, must be zero now
handleTypesunsigned long longBitmask of exportable handle types (see MUmemAllocationHandleType) for this object
numDevicesunsigned intThe number of devices in the multicast team that will bind memory to this object
sizesize_tThe maximum amount of memory that can be bound to this multicast object per device
MUoffset3D_v1 (3 fields)
FieldTypeDescription
xsize_t
ysize_t
zsize_t
MUSA_ARRAY3D_DESCRIPTOR_v2 (6 fields)
FieldTypeDescription
Depthsize_tDepth of 3D array
Flagsunsigned intFlags
FormatMUarray_formatArray format
Heightsize_tHeight of 3D array
NumChannelsunsigned intChannels per array element
Widthsize_tWidth of 3D array
MUSA_ARRAY_DESCRIPTOR_v2 (4 fields)
FieldTypeDescription
FormatMUarray_formatArray format
Heightsize_tHeight of array
NumChannelsunsigned intChannels per array element
Widthsize_tWidth of array
MUSA_ARRAY_MEMORY_REQUIREMENTS_v1 (3 fields)
FieldTypeDescription
alignmentsize_talignment requirement
reservedunsigned int
sizesize_tTotal required memory size
MUSA_ARRAY_SPARSE_PROPERTIES_v1 (8 fields)
FieldTypeDescription
depthunsigned intDepth of sparse tile in elements
flagsunsigned intFlags will either be zero or MU_ARRAY_SPARSE_PROPERTIES_SINGLE_MIPTAIL
heightunsigned intHeight of sparse tile in elements
miptailFirstLevelunsigned intFirst mip level at which the mip tail begins.
miptailSizeunsigned long longTotal size of the mip tail.
reservedunsigned int
tileExtentstruct MUSA_ARRAY_SPARSE_PROPERTIES_v1::@12
widthunsigned intWidth of sparse tile in elements
MUSA_BATCH_MEM_OP_NODE_PARAMS_v1 (4 fields)
FieldTypeDescription
countunsigned int
ctxMUcontext
flagsunsigned int
paramArrayMUstreamBatchMemOpParams *
MUSA_BATCH_MEM_OP_NODE_PARAMS_v2 (4 fields)
FieldTypeDescription
countunsigned intNumber of operations in paramArray.
ctxMUcontextContext to use for the operations.
flagsunsigned intFlags to control the node.
paramArrayMUstreamBatchMemOpParams *Array of batch memory operations.
MUSA_CHILD_GRAPH_NODE_PARAMS (2 fields)
FieldTypeDescription
graphMUgraphThe child graph to clone into the node for node creation, or a handle to the graph owned by the node for node query. The graph must not contain conditional nodes. Graphs containing memory allocation or memory free nodes must set the ownership to be moved to the parent.
ownershipMUgraphChildGraphNodeOwnershipThe ownership relationship of the child graph node.
MUSA_CONDITIONAL_NODE_PARAMS (5 fields)
FieldTypeDescription
ctxMUcontextContext on which to run the node. Must match context used to create the handle and all body nodes.
handleMUgraphConditionalHandleConditional node handle. Handles must be created in advance of creating the node using muGraphConditionalHandleCreate.
phGraph_outMUgraph *MUSA-owned array populated with conditional node child graphs during creation of the node. Valid for the lifetime of the conditional node. The contents of the graph(s) are subject to the following constraints: These graphs may be populated using graph node creation APIs or muStreamBeginCaptureToGraph. MU_GRAPH_COND_TYPE_IF: phGraph_out[0] is executed when the condition is non-zero. If size == 2, phGraph_out[1] will be executed when the condition is zero. MU_GRAPH_COND_TYPE_WHILE: phGraph_out[0] is executed as long as the condition is non-zero. MU_GRAPH_COND_TYPE_SWITCH: phGraph_out[n] is executed when the condition is equal to n. If the condition >= size, no body graph is executed.
sizeunsigned intSize of graph output array. Allowed values are 1 for MU_GRAPH_COND_TYPE_WHILE, 1 or 2 for MU_GRAPH_COND_TYPE_IF, or any value greater than zero for MU_GRAPH_COND_TYPE_SWITCH.
typeMUgraphConditionalNodeTypeType of conditional node.
MUSA_EVENT_RECORD_NODE_PARAMS (1 field)
FieldTypeDescription
eventMUeventThe event to record when the node executes
MUSA_EVENT_WAIT_NODE_PARAMS (1 field)
FieldTypeDescription
eventMUeventThe event to wait on from the node
MUSA_EXT_SEM_SIGNAL_NODE_PARAMS_v1 (3 fields)
FieldTypeDescription
extSemArrayMUexternalSemaphore *Array of external semaphore handles.
numExtSemsunsigned intNumber of handles and parameters supplied in extSemArray and paramsArray.
paramsArrayconst MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS *Array of external semaphore signal parameters.
MUSA_EXT_SEM_SIGNAL_NODE_PARAMS_v2 (3 fields)
FieldTypeDescription
extSemArrayMUexternalSemaphore *Array of external semaphore handles.
numExtSemsunsigned intNumber of handles and parameters supplied in extSemArray and paramsArray.
paramsArrayconst MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS *Array of external semaphore signal parameters.
MUSA_EXT_SEM_WAIT_NODE_PARAMS_v1 (3 fields)
FieldTypeDescription
extSemArrayMUexternalSemaphore *Array of external semaphore handles.
numExtSemsunsigned intNumber of handles and parameters supplied in extSemArray and paramsArray.
paramsArrayconst MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS *Array of external semaphore wait parameters.
MUSA_EXT_SEM_WAIT_NODE_PARAMS_v2 (3 fields)
FieldTypeDescription
extSemArrayMUexternalSemaphore *Array of external semaphore handles.
numExtSemsunsigned intNumber of handles and parameters supplied in extSemArray and paramsArray.
paramsArrayconst MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS *Array of external semaphore wait parameters.
MUSA_EXTERNAL_MEMORY_BUFFER_DESC_v1 (4 fields)
FieldTypeDescription
flagsunsigned intFlags reserved for future use. Must be zero.
offsetunsigned long longOffset into the memory object where the buffer's base is
reservedunsigned int
sizeunsigned long longSize of the buffer
MUSA_EXTERNAL_MEMORY_HANDLE_DESC_v1 (10 fields)
FieldTypeDescription
fdintFile descriptor referencing the memory object. Valid when type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD
flagsunsigned intFlags must either be zero or MUSA_EXTERNAL_MEMORY_DEDICATED
handlevoid *Valid NT handle. Must be NULL if 'name' is non-NULL
handleunion MUSA_EXTERNAL_MEMORY_HANDLE_DESC_v1::@19
mtSciBufObjectconst void *A handle representing an NvSciBuf Object. Valid when type is MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF
nameconst void *Name of a valid memory object. Must be NULL if 'handle' is non-NULL.
reservedunsigned int
sizeunsigned long longSize of the memory allocation
typeMUexternalMemoryHandleTypeType of the handle
win32struct MUSA_EXTERNAL_MEMORY_HANDLE_DESC_v1::@19::@20Win32 handle referencing the semaphore object. Valid when type is one of the following:
MUSA_EXTERNAL_MEMORY_MIPMAPPED_ARRAY_DESC_v1 (4 fields)
FieldTypeDescription
arrayDescMUSA_ARRAY3D_DESCRIPTORFormat, dimension and type of base level of the mipmap chain
numLevelsunsigned intTotal number of levels in the mipmap chain
offsetunsigned long longOffset into the memory object where the base level of the mipmap chain is.
reservedunsigned int
MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC_v1 (9 fields)
FieldTypeDescription
fdintFile descriptor referencing the semaphore object. Valid when type is one of the following:
flagsunsigned intFlags reserved for the future. Must be zero.
handlevoid *Valid NT handle. Must be NULL if 'name' is non-NULL
handleunion MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC_v1::@21
mtSciSyncObjconst void *Valid NvSciSyncObj. Must be non NULL
nameconst void *Name of a valid synchronization primitive. Must be NULL if 'handle' is non-NULL.
reservedunsigned int
typeMUexternalSemaphoreHandleTypeType of the handle
win32struct MUSA_EXTERNAL_SEMAPHORE_HANDLE_DESC_v1::@21::@22Win32 handle referencing the semaphore object. Valid when type is one of the following:
MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1 (10 fields)
FieldTypeDescription
fencestruct MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1::@23::@24Parameters for fence objects
fencevoid *Pointer to NvSciSyncFence. Valid if MUexternalSemaphoreHandleType is of type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC.
flagsunsigned intOnly when MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS is used to signal a MUexternalSemaphore of type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC, the valid flag is MUSA_EXTERNAL_SEMAPHORE_SIGNAL_SKIP_MTSCIBUF_MEMSYNC which indicates that while signaling the MUexternalSemaphore, no memory synchronization operations should be performed for any external memory object imported as MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF. For all other types of MUexternalSemaphore, flags must be zero.
keyunsigned long longValue of key to release the mutex with
keyedMutexstruct MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1::@23::@26Parameters for keyed mutex objects
mtSciSyncunion MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1::@23::@25
paramsstruct MUSA_EXTERNAL_SEMAPHORE_SIGNAL_PARAMS_v1::@23
reservedunsigned long long
reservedunsigned int
valueunsigned long longValue of fence to be signaled
MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1 (11 fields)
FieldTypeDescription
fencestruct MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1::@27::@28Parameters for fence objects
fencevoid *
flagsunsigned intOnly when MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS is used to wait on a MUexternalSemaphore of type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC, the valid flag is MUSA_EXTERNAL_SEMAPHORE_WAIT_SKIP_MTSCIBUF_MEMSYNC which indicates that while waiting for the MUexternalSemaphore, no memory synchronization operations should be performed for any external memory object imported as MU_EXTERNAL_MEMORY_HANDLE_TYPE_MTSCIBUF. For all other types of MUexternalSemaphore, flags must be zero.
keyunsigned long longValue of key to acquire the mutex with
keyedMutexstruct MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1::@27::@30Parameters for keyed mutex objects
mtSciSyncunion MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1::@27::@29Pointer to NvSciSyncFence. Valid if MUexternalSemaphoreHandleType is of type MU_EXTERNAL_SEMAPHORE_HANDLE_TYPE_MTSCISYNC.
paramsstruct MUSA_EXTERNAL_SEMAPHORE_WAIT_PARAMS_v1::@27
reservedunsigned long long
reservedunsigned int
timeoutMsunsigned intTimeout in milliseconds to wait to acquire the mutex
valueunsigned long longValue of fence to be waited on
MUSA_GRAPH_INSTANTIATE_PARAMS (4 fields)
FieldTypeDescription
flagsmuuint64_tInstantiation flags
hErrNode_outMUgraphNodeThe node which caused instantiation to fail, if any
hUploadStreamMUstreamUpload stream
result_outMUgraphInstantiateResultWhether instantiation was successful. If it failed, the reason why
MUSA_HOST_NODE_PARAMS_v1 (2 fields)
FieldTypeDescription
fnMUhostFnThe function to call when the node executes
userDatavoid *Argument to pass to the function
MUSA_HOST_NODE_PARAMS_v2 (3 fields)
FieldTypeDescription
fnMUhostFnThe function to call when the node executes
syncModeunsigned intThe sync mode to use for the host task
userDatavoid *Argument to pass to the function
MUSA_KERNEL_NODE_PARAMS_v1 (10 fields)
FieldTypeDescription
blockDimXunsigned intX dimension of each thread block
blockDimYunsigned intY dimension of each thread block
blockDimZunsigned intZ dimension of each thread block
extravoid **Extra options
funcMUfunctionKernel to launch
gridDimXunsigned intWidth of grid in blocks
gridDimYunsigned intHeight of grid in blocks
gridDimZunsigned intDepth of grid in blocks
kernelParamsvoid **Array of pointers to kernel parameters
sharedMemBytesunsigned intDynamic shared-memory size per thread block in bytes
MUSA_KERNEL_NODE_PARAMS_v2 (12 fields)
FieldTypeDescription
blockDimXunsigned intX dimension of each thread block
blockDimYunsigned intY dimension of each thread block
blockDimZunsigned intZ dimension of each thread block
ctxMUcontextContext for the kernel task to run in. The value NULL will indicate the current context should be used by the api. This field is ignored if func is set.
extravoid **Extra options
funcMUfunctionKernel to launch
gridDimXunsigned intWidth of grid in blocks
gridDimYunsigned intHeight of grid in blocks
gridDimZunsigned intDepth of grid in blocks
kernMUkernelKernel to launch, will only be referenced if func is NULL
kernelParamsvoid **Array of pointers to kernel parameters
sharedMemBytesunsigned intDynamic shared-memory size per thread block in bytes
MUSA_KERNEL_NODE_PARAMS_v3 (12 fields)
FieldTypeDescription
blockDimXunsigned intX dimension of each thread block
blockDimYunsigned intY dimension of each thread block
blockDimZunsigned intZ dimension of each thread block
ctxMUcontextContext for the kernel task to run in. The value NULL will indicate the current context should be used by the api. This field is ignored if func is set.
extravoid **Extra options
funcMUfunctionKernel to launch
gridDimXunsigned intWidth of grid in blocks
gridDimYunsigned intHeight of grid in blocks
gridDimZunsigned intDepth of grid in blocks
kernMUkernelKernel to launch, will only be referenced if func is NULL
kernelParamsvoid **Array of pointers to kernel parameters
sharedMemBytesunsigned intDynamic shared-memory size per thread block in bytes
MUSA_LAUNCH_PARAMS_v1 (10 fields)
FieldTypeDescription
blockDimXunsigned intX dimension of each thread block
blockDimYunsigned intY dimension of each thread block
blockDimZunsigned intZ dimension of each thread block
functionMUfunctionKernel to launch
gridDimXunsigned intWidth of grid in blocks
gridDimYunsigned intHeight of grid in blocks
gridDimZunsigned intDepth of grid in blocks
hStreamMUstreamStream identifier
kernelParamsvoid **Array of pointers to kernel parameters
sharedMemBytesunsigned intDynamic shared-memory size per thread block in bytes
MUSA_MEM_ALLOC_NODE_PARAMS_v1 (5 fields)
FieldTypeDescription
accessDescCountsize_tin: number of memory access descriptors. Must not exceed the number of GPUs.
accessDescsconst MUmemAccessDesc *in: array of memory access descriptors. Used to describe peer GPU access
bytesizesize_tin: size in bytes of the requested allocation
dptrMUdeviceptrout: address of the allocation returned by MUSA
poolPropsMUmemPoolPropsin: location where the allocation should reside (specified in location). handleTypes must be MU_MEM_HANDLE_TYPE_NONE. IPC is not supported.
MUSA_MEM_ALLOC_NODE_PARAMS_v2 (5 fields)
FieldTypeDescription
accessDescCountsize_tin: number of memory access descriptors. Must not exceed the number of GPUs.
accessDescsconst MUmemAccessDesc *in: array of memory access descriptors. Used to describe peer GPU access
bytesizesize_tin: size in bytes of the requested allocation
dptrMUdeviceptrout: address of the allocation returned by MUSA
poolPropsMUmemPoolPropsin: location where the allocation should reside (specified in location). handleTypes must be MU_MEM_HANDLE_TYPE_NONE. IPC is not supported.
MUSA_MEM_ATOMIC_NODE_PARAMS_v1 (4 fields)
FieldTypeDescription
dstMUdeviceptr
elementCountsize_t
operationMUatomicType
srcMUdeviceptr
MUSA_MEM_ATOMIC_VALUE_NODE_PARAMS_v1 (3 fields)
FieldTypeDescription
dstMUdeviceptr
operationMUatomicValueType
valuemuuint64_t
MUSA_MEM_FREE_NODE_PARAMS (1 field)
FieldTypeDescription
dptrMUdeviceptrin: the pointer to free
MUSA_MEM_TRANSFER_NODE_PARAMS_v1 (3 fields)
FieldTypeDescription
ByteCountsize_t
dstMUdeviceptr
srcMUdeviceptr
MUSA_MEM_WAIT_WRITE_NODE_PARAMS_v1 (4 fields)
FieldTypeDescription
addrMUdeviceptr
flagsunsigned int
operationMUstreamBatchMemOpType
valuemuuint64_t
MUSA_MEMCPY2D_v2 (16 fields)
FieldTypeDescription
dstArrayMUarrayDestination array reference
dstDeviceMUdeviceptrDestination device pointer
dstHostvoid *Destination host pointer
dstMemoryTypeMUmemorytypeDestination memory type (host, device, array)
dstPitchsize_tDestination pitch (ignored when dst is array)
dstXInBytessize_tDestination X in bytes
dstYsize_tDestination Y
Heightsize_tHeight of 2D memory copy
srcArrayMUarraySource array reference
srcDeviceMUdeviceptrSource device pointer
srcHostconst void *Source host pointer
srcMemoryTypeMUmemorytypeSource memory type (host, device, array)
srcPitchsize_tSource pitch (ignored when src is array)
srcXInBytessize_tSource X in bytes
srcYsize_tSource Y
WidthInBytessize_tWidth of 2D memory copy in bytes
MUSA_MEMCPY3D_BATCH_OP_v1 (5 fields)
FieldTypeDescription
dstMUmemcpy3DOperandDestination memcpy operand.
extentMUextent3DExtents of the memcpy between src and dst. The width, height and depth components must not be 0.
flagsunsigned intAdditional flags for copies with this attribute. See MUmemcpyFlags
srcMUmemcpy3DOperandSource memcpy operand.
srcAccessOrderMUmemcpySrcAccessOrderSource access ordering to be observed for copy from src to dst.
MUSA_MEMCPY3D_PEER_v1 (25 fields)
FieldTypeDescription
Depthsize_tDepth of 3D memory copy
dstArrayMUarrayDestination array reference
dstContextMUcontextDestination context (ignored with dstMemoryType is MU_MEMORYTYPE_ARRAY)
dstDeviceMUdeviceptrDestination device pointer
dstHeightsize_tDestination height (ignored when dst is array; may be 0 if Depth==1)
dstHostvoid *Destination host pointer
dstLODsize_tDestination LOD
dstMemoryTypeMUmemorytypeDestination memory type (host, device, array)
dstPitchsize_tDestination pitch (ignored when dst is array)
dstXInBytessize_tDestination X in bytes
dstYsize_tDestination Y
dstZsize_tDestination Z
Heightsize_tHeight of 3D memory copy
srcArrayMUarraySource array reference
srcContextMUcontextSource context (ignored with srcMemoryType is MU_MEMORYTYPE_ARRAY)
srcDeviceMUdeviceptrSource device pointer
srcHeightsize_tSource height (ignored when src is array; may be 0 if Depth==1)
srcHostconst void *Source host pointer
srcLODsize_tSource LOD
srcMemoryTypeMUmemorytypeSource memory type (host, device, array)
srcPitchsize_tSource pitch (ignored when src is array)
srcXInBytessize_tSource X in bytes
srcYsize_tSource Y
srcZsize_tSource Z
WidthInBytessize_tWidth of 3D memory copy in bytes
MUSA_MEMCPY3D_v2 (25 fields)
FieldTypeDescription
Depthsize_tDepth of 3D memory copy
dstArrayMUarrayDestination array reference
dstDeviceMUdeviceptrDestination device pointer
dstHeightsize_tDestination height (ignored when dst is array; may be 0 if Depth==1)
dstHostvoid *Destination host pointer
dstLODsize_tDestination LOD
dstMemoryTypeMUmemorytypeDestination memory type (host, device, array)
dstPitchsize_tDestination pitch (ignored when dst is array)
dstXInBytessize_tDestination X in bytes
dstYsize_tDestination Y
dstZsize_tDestination Z
Heightsize_tHeight of 3D memory copy
reserved0void *Must be NULL
reserved1void *Must be NULL
srcArrayMUarraySource array reference
srcDeviceMUdeviceptrSource device pointer
srcHeightsize_tSource height (ignored when src is array; may be 0 if Depth==1)
srcHostconst void *Source host pointer
srcLODsize_tSource LOD
srcMemoryTypeMUmemorytypeSource memory type (host, device, array)
srcPitchsize_tSource pitch (ignored when src is array)
srcXInBytessize_tSource X in bytes
srcYsize_tSource Y
srcZsize_tSource Z
WidthInBytessize_tWidth of 3D memory copy in bytes
MUSA_MEMCPY_NODE_PARAMS (4 fields)
FieldTypeDescription
copyCtxMUcontextContext on which to run the node
copyParamsMUSA_MEMCPY3DParameters for the memory copy
flagsintMust be zero
reservedintMust be zero
MUSA_MEMSET_NODE_PARAMS_v1 (6 fields)
FieldTypeDescription
dstMUdeviceptrDestination device pointer
elementSizeunsigned intSize of each element in bytes. Must be 1, 2, or 4.
heightsize_tNumber of rows
pitchsize_tPitch of destination device pointer. Unused if height is 1
valueunsigned intValue to be set
widthsize_tWidth of the row in elements
MUSA_MEMSET_NODE_PARAMS_v2 (7 fields)
FieldTypeDescription
ctxMUcontextContext on which to run the node
dstMUdeviceptrDestination device pointer
elementSizeunsigned intSize of each element in bytes. Must be 1, 2, or 4.
heightsize_tNumber of rows
pitchsize_tPitch of destination device pointer. Unused if height is 1
valueunsigned intValue to be set
widthsize_tWidth of the row in elements
MUSA_POINTER_ATTRIBUTE_P2P_TOKENS_v1 (2 fields)
FieldTypeDescription
p2pTokenunsigned long long
vaSpaceTokenunsigned int
MUSA_RESOURCE_DESC_v1 (18 fields)
FieldTypeDescription
arraystruct MUSA_RESOURCE_DESC_v1::@13::@14
devPtrMUdeviceptrDevice pointer
flagsunsigned intFlags (must be zero)
formatMUarray_formatArray format
hArrayMUarrayMUSA array
heightsize_tHeight of the array in elements
hMipmappedArrayMUmipmappedArrayMUSA mipmapped array
linearstruct MUSA_RESOURCE_DESC_v1::@13::@16
mipmapstruct MUSA_RESOURCE_DESC_v1::@13::@15
numChannelsunsigned intChannels per array element
pitch2Dstruct MUSA_RESOURCE_DESC_v1::@13::@17
pitchInBytessize_tPitch between two rows in bytes
resunion MUSA_RESOURCE_DESC_v1::@13
reservedint
reservedstruct MUSA_RESOURCE_DESC_v1::@13::@18
resTypeMUresourcetypeResource type
sizeInBytessize_tSize in bytes
widthsize_tWidth of the array in elements
MUSA_RESOURCE_VIEW_DESC_v1 (9 fields)
FieldTypeDescription
depthsize_tDepth of the resource view
firstLayerunsigned intFirst layer index
firstMipmapLevelunsigned intFirst defined mipmap level
formatMUresourceViewFormatResource view format
heightsize_tHeight of the resource view
lastLayerunsigned intLast layer index
lastMipmapLevelunsigned intLast defined mipmap level
reservedunsigned int
widthsize_tWidth of the resource view
MUSA_TEXTURE_DESC_v1 (10 fields)
FieldTypeDescription
addressModeMUaddress_modeAddress modes
borderColorfloatBorder Color
filterModeMUfilter_modeFilter mode
flagsunsigned intFlags
maxAnisotropyunsigned intMaximum anisotropy ratio
maxMipmapLevelClampfloatMipmap maximum level clamp
minMipmapLevelClampfloatMipmap minimum level clamp
mipmapFilterModeMUfilter_modeMipmap filter mode
mipmapLevelBiasfloatMipmap level bias
reservedint
MUstreamBatchMemOpParams_v1 (7 fields)
FieldTypeDescription
atomicReductionstruct MUstreamBatchMemOpParams_v1::MUstreamMemOpAtomicReductionParams_st
flushRemoteWritesstruct MUstreamBatchMemOpParams_v1::MUstreamMemOpFlushRemoteWritesParams_st
memoryBarrierstruct MUstreamBatchMemOpParams_v1::MUstreamMemOpMemoryBarrierParams_st
operationMUstreamBatchMemOpType
padmuuint64_t
waitValuestruct MUstreamBatchMemOpParams_v1::MUstreamMemOpWaitValueParams_st
writeValuestruct MUstreamBatchMemOpParams_v1::MUstreamMemOpWriteValueParams_st
MUstreamBatchMemOpParams_v1::MUstreamMemOpAtomicReductionParams_st (7 fields)
FieldTypeDescription
addressMUdeviceptrThe address the atomic operation will be operated on
aliasMUdeviceptrFor driver internal use. Initial value is unimportant.
dataTypeMUstreamAtomicReductionDataTypeSee MUstreamAtomicReductionDataType
flagsunsigned intMust be 0
operationMUstreamBatchMemOpType
reductionOpMUstreamAtomicReductionOpTypeSee MUstreamAtomicReductionOpType
valuemuuint64_tThe operand value the atomic operation will operate with
MUstreamBatchMemOpParams_v1::MUstreamMemOpFlushRemoteWritesParams_st (2 fields)
FieldTypeDescription
flagsunsigned int
operationMUstreamBatchMemOpType
MUstreamBatchMemOpParams_v1::MUstreamMemOpMemoryBarrierParams_st (2 fields)
FieldTypeDescription
flagsunsigned int
operationMUstreamBatchMemOpType< Only supported in the _v2 API
MUstreamBatchMemOpParams_v1::MUstreamMemOpWaitValueParams_st (7 fields)
FieldTypeDescription
@1union MUstreamBatchMemOpParams_v1::MUstreamMemOpWaitValueParams_st::@0
addressMUdeviceptr
aliasMUdeviceptrFor driver internal use. Initial value is unimportant.
flagsunsigned int
operationMUstreamBatchMemOpType
valuemuuint32_t
value64muuint64_t
MUstreamBatchMemOpParams_v1::MUstreamMemOpWriteValueParams_st (7 fields)
FieldTypeDescription
@3union MUstreamBatchMemOpParams_v1::MUstreamMemOpWriteValueParams_st::@2
addressMUdeviceptr
aliasMUdeviceptrFor driver internal use. Initial value is unimportant.
flagsunsigned int
operationMUstreamBatchMemOpType
valuemuuint32_t
value64muuint64_t
MUstreamCigCaptureParams (1 field)
FieldTypeDescription
streamCigParamsMUstreamCigParam *CIG (MUSA in Graphics) parameters for sharing command list data from D3D12 graphics clients.
MUstreamCigParam (2 fields)
FieldTypeDescription
streamSharedDatavoid *Graphics client data handle (ID3D12CommandList/ID3D12GraphicsCommandList).
streamSharedDataTypeMUstreamCigDataTypeType of shared data from graphics client (D3D12).
MUtensorDescriptor (1 field)
FieldTypeDescription
opaquemuuint64_t
MUuuid (1 field)
FieldTypeDescription
byteschar< MUSA definition of UUID

7. Deprecated List​

This section lists Driver API entries marked deprecated.

CategoryName
enumMUsharedconfig
enumvalueMU_CTX_BLOCKING_SYNC
enumvalueMU_CTX_MAP_HOST
enumvalueMU_DEVICE_P2P_ATTRIBUTE_ACCESS_ACCESS_SUPPORTED
enumvalueMU_JIT_FMA
enumvalueMU_JIT_FTZ
enumvalueMU_JIT_INPUT_NVVM
enumvalueMU_JIT_LTO
enumvalueMU_JIT_NEW_SM3X_OPT
enumvalueMU_JIT_OPTIMIZE_UNUSED_DEVICE_VARIABLES
enumvalueMU_JIT_PREC_DIV
enumvalueMU_JIT_PREC_SQRT
enumvalueMU_JIT_REFERENCED_KERNEL_COUNT
enumvalueMU_JIT_REFERENCED_KERNEL_NAMES
enumvalueMU_JIT_REFERENCED_VARIABLE_COUNT
enumvalueMU_JIT_REFERENCED_VARIABLE_NAMES
enumvalueMUSA_ERROR_CONTEXT_ALREADY_CURRENT
enumvalueMUSA_ERROR_PROFILER_ALREADY_STARTED
enumvalueMUSA_ERROR_PROFILER_ALREADY_STOPPED
enumvalueMUSA_ERROR_PROFILER_NOT_INITIALIZED
functionmuCtxAttach
functionmuCtxDetach
functionmuCtxGetSharedMemConfig
functionmuCtxSetSharedMemConfig
functionmuDeviceComputeCapability
functionmuDeviceGetProperties
functionmuFuncSetSharedMemConfig
functionmuLaunchHostFunc
functionmuModuleGetSurfRef
functionmuModuleGetTexRef
functionmuSurfRefGetArray
functionmuSurfRefSetArray
functionmuTexRefCreate
functionmuTexRefDestroy
functionmuTexRefGetAddress
functionmuTexRefGetAddressMode
functionmuTexRefGetArray
functionmuTexRefGetBorderColor
functionmuTexRefGetFilterMode
functionmuTexRefGetFlags
functionmuTexRefGetFormat
functionmuTexRefGetMaxAnisotropy
functionmuTexRefGetMipmapFilterMode
functionmuTexRefGetMipmapLevelBias
functionmuTexRefGetMipmapLevelClamp
functionmuTexRefGetMipmappedArray
functionmuTexRefSetAddress
functionmuTexRefSetAddress2D
functionmuTexRefSetAddressMode
functionmuTexRefSetArray
functionmuTexRefSetBorderColor
functionmuTexRefSetFilterMode
functionmuTexRefSetFlags
functionmuTexRefSetFormat
functionmuTexRefSetMaxAnisotropy
functionmuTexRefSetMipmapFilterMode
functionmuTexRefSetMipmapLevelBias
functionmuTexRefSetMipmapLevelClamp
functionmuTexRefSetMipmappedArray

8. Experimental List​

These APIs are included in the MUSA SDK 5.2.0 release scope and are marked experimental in this reference.

ModuleAPI
Stream Ordered Memory AllocatormuMemGetDefaultMemPool
Stream Ordered Memory AllocatormuMemGetMemPool
Stream Ordered Memory AllocatormuMemSetMemPool
Execution ControlmuFuncGetParamCount
Graph ManagementmuGraphNodeGetContainingGraph
Graph ManagementmuGraphNodeGetLocalId
Graph ManagementmuGraphNodeGetToolsId
Graph ManagementmuGraphGetId
Graph ManagementmuGraphExecGetId
Graph ManagementmuGraphNodeGetParams
Error Log ManagementmuLogsRegisterCallback
Error Log ManagementmuLogsUnregisterCallback
Error Log ManagementmuLogsCurrent
Error Log ManagementmuLogsDumpToFile
Error Log ManagementmuLogsDumpToMemory

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。