CUDA Runtime API :: CUDA Toolkit Documentation

6.11. 内存管理

本节介绍CUDA运行时应用程序编程接口的内存管理功能。

部分函数在C++ API Routines模块中提供了重载的C++ API模板版本，相关文档单独列出。

Functions

__host__ cudaError_t cudaArrayGetInfo ( cudaChannelFormatDesc* desc, cudaExtent* extent, unsigned int* flags, cudaArray_t array ): Gets info about the specified cudaArray.
__host__ cudaError_t cudaArrayGetMemoryRequirements ( cudaArrayMemoryRequirements* memoryRequirements, cudaArray_t array, int device ): Returns the memory requirements of a CUDA array.
__host__ cudaError_t cudaArrayGetPlane ( cudaArray_t* pPlaneArray, cudaArray_t hArray, unsigned int planeIdx ): Gets a CUDA array plane from a CUDA array.
__host__ cudaError_t cudaArrayGetSparseProperties ( cudaArraySparseProperties* sparseProperties, cudaArray_t array ): Returns the layout properties of a sparse CUDA array.
__host__ __device__ cudaError_t cudaFree ( void* devPtr ): Frees memory on the device.
__host__ cudaError_t cudaFreeArray ( cudaArray_t array ): Frees an array on the device.
__host__ cudaError_t cudaFreeHost ( void* ptr ): Frees page-locked memory.
__host__ cudaError_t cudaFreeMipmappedArray ( cudaMipmappedArray_t mipmappedArray ): Frees a mipmapped array on the device.
__host__ cudaError_t cudaGetMipmappedArrayLevel ( cudaArray_t* levelArray, cudaMipmappedArray_const_t mipmappedArray, unsigned int level ): Gets a mipmap level of a CUDA mipmapped array.
__host__ cudaError_t cudaGetSymbolAddress ( void** devPtr, const void* symbol ): Finds the address associated with a CUDA symbol.
__host__ cudaError_t cudaGetSymbolSize ( size_t* size, const void* symbol ): Finds the size of the object associated with a CUDA symbol.
__host__ cudaError_t cudaHostAlloc ( void** pHost, size_t size, unsigned int flags ): Allocates page-locked memory on the host.
__host__ cudaError_t cudaHostGetDevicePointer ( void** pDevice, void* pHost, unsigned int flags ): Passes back device pointer of mapped host memory allocated by cudaHostAlloc or registered by cudaHostRegister.
__host__ cudaError_t cudaHostGetFlags ( unsigned int* pFlags, void* pHost ): Passes back flags used to allocate pinned host memory allocated by cudaHostAlloc.
__host__ cudaError_t cudaHostRegister ( void* ptr, size_t size, unsigned int flags ): Registers an existing host memory range for use by CUDA.
__host__ cudaError_t cudaHostUnregister ( void* ptr ): Unregisters a memory range that was registered with cudaHostRegister.
__host__ __device__ cudaError_t cudaMalloc ( void** devPtr, size_t size ): Allocate memory on the device.
__host__ cudaError_t cudaMalloc3D ( cudaPitchedPtr* pitchedDevPtr, cudaExtent extent ): Allocates logical 1D, 2D, or 3D memory objects on the device.
__host__ cudaError_t cudaMalloc3DArray ( cudaArray_t* array, const cudaChannelFormatDesc* desc, cudaExtent extent, unsigned int flags = 0 ): Allocate an array on the device.
__host__ cudaError_t cudaMallocArray ( cudaArray_t* array, const cudaChannelFormatDesc* desc, size_t width, size_t height = 0, unsigned int flags = 0 ): Allocate an array on the device.
__host__ cudaError_t cudaMallocHost ( void** ptr, size_t size ): Allocates page-locked memory on the host.
__host__ cudaError_t cudaMallocManaged ( void** devPtr, size_t size, unsigned int flags = cudaMemAttachGlobal ): Allocates memory that will be automatically managed by the Unified Memory system.
__host__ cudaError_t cudaMallocMipmappedArray ( cudaMipmappedArray_t* mipmappedArray, const cudaChannelFormatDesc* desc, cudaExtent extent, unsigned int numLevels, unsigned int flags = 0 ): Allocate a mipmapped array on the device.
__host__ cudaError_t cudaMallocPitch ( void** devPtr, size_t* pitch, size_t width, size_t height ): Allocates pitched memory on the device.
__host__ cudaError_t cudaMemAdvise ( const void* devPtr, size_t count, cudaMemoryAdvise advice, int device ): Advise about the usage of a given memory range.
__host__ cudaError_t cudaMemAdvise_v2 ( const void* devPtr, size_t count, cudaMemoryAdvise advice, cudaMemLocation location ): Advise about the usage of a given memory range.
__host__ cudaError_t cudaMemGetInfo ( size_t* free, size_t* total ): Gets free and total device memory.
__host__ cudaError_t cudaMemPrefetchAsync ( const void* devPtr, size_t count, int dstDevice, cudaStream_t stream = 0 ): Prefetches memory to the specified destination device.
__host__ cudaError_t cudaMemPrefetchAsync_v2 ( const void* devPtr, size_t count, cudaMemLocation location, unsigned int flags, cudaStream_t stream = 0 ): Prefetches memory to the specified destination location.
__host__ cudaError_t cudaMemRangeGetAttribute ( void* data, size_t dataSize, cudaMemRangeAttribute attribute, const void* devPtr, size_t count ): Query an attribute of a given memory range.
__host__ cudaError_t cudaMemRangeGetAttributes ( void** data, size_t* dataSizes, cudaMemRangeAttribute ** attributes, size_t numAttributes, const void* devPtr, size_t count ): Query attributes of a given memory range.
__host__ cudaError_t cudaMemcpy ( void* dst, const void* src, size_t count, cudaMemcpyKind kind ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2D ( void* dst, size_t dpitch, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2DArrayToArray ( cudaArray_t dst, size_t wOffsetDst, size_t hOffsetDst, cudaArray_const_t src, size_t wOffsetSrc, size_t hOffsetSrc, size_t width, size_t height, cudaMemcpyKind kind = cudaMemcpyDeviceToDevice ): Copies data between host and device.
__host__ __device__ cudaError_t cudaMemcpy2DAsync ( void* dst, size_t dpitch, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2DFromArray ( void* dst, size_t dpitch, cudaArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, cudaMemcpyKind kind ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2DFromArrayAsync ( void* dst, size_t dpitch, cudaArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2DToArray ( cudaArray_t dst, size_t wOffset, size_t hOffset, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy2DToArrayAsync ( cudaArray_t dst, size_t wOffset, size_t hOffset, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data between host and device.
__host__ cudaError_t cudaMemcpy3D ( const cudaMemcpy3DParms* p ): Copies data between 3D objects.
__host__ __device__ cudaError_t cudaMemcpy3DAsync ( const cudaMemcpy3DParms* p, cudaStream_t stream = 0 ): Copies data between 3D objects.
__host__ cudaError_t cudaMemcpy3DBatchAsync ( size_t numOps, cudaMemcpy3DBatchOp* opList, size_t* failIdx, unsigned long long flags, cudaStream_t stream ): Performs a batch of 3D memory copies asynchronously.
__host__ cudaError_t cudaMemcpy3DPeer ( const cudaMemcpy3DPeerParms* p ): Copies memory between devices.
__host__ cudaError_t cudaMemcpy3DPeerAsync ( const cudaMemcpy3DPeerParms* p, cudaStream_t stream = 0 ): Copies memory between devices asynchronously.
__host__ __device__ cudaError_t cudaMemcpyAsync ( void* dst, const void* src, size_t count, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data between host and device.
__host__ cudaError_t cudaMemcpyBatchAsync ( void** dsts, void** srcs, size_t* sizes, size_t count, cudaMemcpyAttributes* attrs, size_t* attrsIdxs, size_t numAttrs, size_t* failIdx, cudaStream_t stream ): Performs a batch of memory copies asynchronously.
__host__ cudaError_t cudaMemcpyFromSymbol ( void* dst, const void* symbol, size_t count, size_t offset = 0, cudaMemcpyKind kind = cudaMemcpyDeviceToHost ): Copies data from the given symbol on the device.
__host__ cudaError_t cudaMemcpyFromSymbolAsync ( void* dst, const void* symbol, size_t count, size_t offset, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data from the given symbol on the device.
__host__ cudaError_t cudaMemcpyPeer ( void* dst, int dstDevice, const void* src, int srcDevice, size_t count ): Copies memory between two devices.
__host__ cudaError_t cudaMemcpyPeerAsync ( void* dst, int dstDevice, const void* src, int srcDevice, size_t count, cudaStream_t stream = 0 ): Copies memory between two devices asynchronously.
__host__ cudaError_t cudaMemcpyToSymbol ( const void* symbol, const void* src, size_t count, size_t offset = 0, cudaMemcpyKind kind = cudaMemcpyHostToDevice ): Copies data to the given symbol on the device.
__host__ cudaError_t cudaMemcpyToSymbolAsync ( const void* symbol, const void* src, size_t count, size_t offset, cudaMemcpyKind kind, cudaStream_t stream = 0 ): Copies data to the given symbol on the device.
__host__ cudaError_t cudaMemset ( void* devPtr, int value, size_t count ): Initializes or sets device memory to a value.
__host__ cudaError_t cudaMemset2D ( void* devPtr, size_t pitch, int value, size_t width, size_t height ): Initializes or sets device memory to a value.
__host__ __device__ cudaError_t cudaMemset2DAsync ( void* devPtr, size_t pitch, int value, size_t width, size_t height, cudaStream_t stream = 0 ): Initializes or sets device memory to a value.
__host__ cudaError_t cudaMemset3D ( cudaPitchedPtr pitchedDevPtr, int value, cudaExtent extent ): Initializes or sets device memory to a value.
__host__ __device__ cudaError_t cudaMemset3DAsync ( cudaPitchedPtr pitchedDevPtr, int value, cudaExtent extent, cudaStream_t stream = 0 ): Initializes or sets device memory to a value.
__host__ __device__ cudaError_t cudaMemsetAsync ( void* devPtr, int value, size_t count, cudaStream_t stream = 0 ): Initializes or sets device memory to a value.
__host__ cudaError_t cudaMipmappedArrayGetMemoryRequirements ( cudaArrayMemoryRequirements* memoryRequirements, cudaMipmappedArray_t mipmap, int device ): Returns the memory requirements of a CUDA mipmapped array.
__host__ cudaError_t cudaMipmappedArrayGetSparseProperties ( cudaArraySparseProperties* sparseProperties, cudaMipmappedArray_t mipmap ): Returns the layout properties of a sparse CUDA mipmapped array.
__host__ cudaExtent make_cudaExtent ( size_t w, size_t h, size_t d ): Returns a cudaExtent based on input parameters.
__host__ cudaPitchedPtr make_cudaPitchedPtr ( void* d, size_t p, size_t xsz, size_t ysz ): Returns a cudaPitchedPtr based on input parameters.
__host__ cudaPos make_cudaPos ( size_t x, size_t y, size_t z ): Returns a cudaPos based on input parameters.

Functions

__host__ cudaError_t cudaArrayGetInfo ( cudaChannelFormatDesc* desc, cudaExtent* extent, unsigned int* flags, cudaArray_t array )

获取指定cudaArray的相关信息。

参数

desc: - Returned array type
extent: - Returned array shape. 2D arrays will have depth of zero
flags: - Returned array flags
array: - The cudaArray to get info for

cudaSuccess, cudaErrorInvalidValue

描述

分别在*desc、*extent和*flags中返回array的类型、形状和标志。

*desc、*extent 和 *flags 中的任何一个都可以指定为 NULL。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cuArrayGetDescriptor, cuArray3DGetDescriptor

__host__ cudaError_t cudaArrayGetMemoryRequirements ( cudaArrayMemoryRequirements* memoryRequirements, cudaArray_t array, int device )

返回CUDA数组的内存需求。

参数

memoryRequirements: - Pointer to cudaArrayMemoryRequirements
array: - CUDA array to get the memory requirements of
device: - Device to get the memory requirements for

cudaSuccess cudaErrorInvalidValue

描述

返回CUDA数组在memoryRequirements中的内存需求。如果CUDA数组未使用标志cudaArrayDeferredMapping分配，将返回cudaErrorInvalidValue。

cudaArrayMemoryRequirements::size中的返回值表示CUDA数组的总大小。cudaArrayMemoryRequirements::alignment中的返回值表示映射CUDA数组所需的对齐要求。

另请参阅：

cudaMipmappedArrayGetMemoryRequirements

__host__ cudaError_t cudaArrayGetPlane ( cudaArray_t* pPlaneArray, cudaArray_t hArray, unsigned int planeIdx )

从CUDA数组中获取一个CUDA数组平面。

参数

pPlaneArray: - Returned CUDA array referenced by the planeIdx
hArray: - CUDA array
planeIdx: - Plane index

cudaSuccess, cudaErrorInvalidValue cudaErrorInvalidResourceHandle

描述

在pPlaneArray中返回一个表示CUDA数组hArray单个格式平面的CUDA数组。

如果planeIdx大于此数组中的最大平面数，或者如果数组不具有多平面格式（例如：cudaChannelFormatKindNV12），则将返回cudaErrorInvalidValue。

请注意，如果hArray的格式是cudaChannelFormatKindNV12，那么为planeIdx传入0将返回一个与hArray大小相同但具有单8位通道且格式类型为cudaChannelFormatKindUnsigned的CUDA数组。如果为planeIdx传入1，则返回的CUDA数组高度和宽度为hArray的一半，具有两个8位通道且格式类型为cudaChannelFormatKindUnsigned。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。

另请参阅：

cuArrayGetPlane

__host__ cudaError_t cudaArrayGetSparseProperties ( cudaArraySparseProperties* sparseProperties, cudaArray_t array )

返回稀疏CUDA数组的布局属性。

参数

sparseProperties: - Pointer to return the cudaArraySparseProperties
array: - The CUDA array to get the sparse properties of

cudaSuccess cudaErrorInvalidValue

描述

返回稀疏CUDA数组在sparseProperties中的布局属性。如果CUDA数组不是使用cudaArraySparse标志分配的，将返回cudaErrorInvalidValue。

如果cudaArraySparseProperties::flags中的返回值包含cudaArraySparsePropertiesSingleMipTail，则cudaArraySparseProperties::miptailSize表示数组的总大小。否则，该值将为零。此外，cudaArraySparseProperties::miptailFirstLevel中的返回值始终为零。请注意，array必须是通过cudaMallocArray或cudaMalloc3DArray分配的。对于使用cudaMipmappedArrayGetLevel获取的CUDA数组，将返回cudaErrorInvalidValue。相反，必须使用cudaMipmappedArrayGetSparseProperties来获取array所属的整个CUDA mipmapped数组的稀疏属性。

另请参阅：

cudaMipmappedArrayGetSparseProperties, cuMemMapArrayAsync

__host__ __device__ cudaError_t cudaFree ( void* devPtr )

释放设备上的内存。

参数

devPtr: - Device pointer to memory to free

cudaSuccess, cudaErrorInvalidValue

描述

释放由devPtr指向的内存空间，该指针必须是通过之前调用以下内存分配API之一返回的 - cudaMalloc(), cudaMallocPitch(), cudaMallocManaged(), cudaMallocAsync(), cudaMallocFromPoolAsync()。

注意 - 当指针是通过cudaMallocAsync或cudaMallocFromPoolAsync分配时，此API不会执行任何隐式同步。调用方必须确保在调用cudaFree之前已完成对这些指针的所有访问。为了获得最佳性能和内存重用，用户应使用cudaFreeAsync来释放通过流序内存分配器分配的内存。对于所有其他指针，此API可能会执行隐式同步。

如果之前已经调用过cudaFree(devPtr)，则会返回错误。如果devPtr为0，则不执行任何操作。cudaFree()在失败时会返回cudaErrorValue。

设备版本的cudaFree不能用于通过主机API分配的*devPtr，反之亦然。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaMallocManaged, cudaMallocArray, cudaFreeArray, cudaMallocAsync, cudaMallocFromPoolAsync cudaMallocHost ( C API), cudaFreeHost, cudaMalloc3D, cudaMalloc3DArray, cudaFreeAsync cudaHostAlloc, cuMemFree

__host__ cudaError_t cudaFreeArray ( cudaArray_t array )

释放设备上的数组。

参数

array: - Pointer to array to free

cudaSuccess, cudaErrorInvalidValue

描述

释放由先前调用cudaMallocArray()返回的CUDA数组array。如果devPtr为0，则不执行任何操作。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaFree, cudaMallocArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, cuArrayDestroy

__host__ cudaError_t cudaFreeHost ( void* ptr )

释放页面锁定的内存。

参数

ptr: - Pointer to memory to free

cudaSuccess, cudaErrorInvalidValue

描述

释放由hostPtr指向的内存空间，该指针必须是通过之前调用cudaMallocHost()或cudaHostAlloc()返回的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaFree, cudaMallocArray, cudaFreeArray, cudaMallocHost ( C API), cudaMalloc3D, cudaMalloc3DArray, cudaHostAlloc, cuMemFreeHost

__host__ cudaError_t cudaFreeMipmappedArray ( cudaMipmappedArray_t mipmappedArray )

释放设备上的mipmapped数组。

参数

mipmappedArray: - Pointer to mipmapped array to free

cudaSuccess, cudaErrorInvalidValue

描述

释放CUDA mipmapped数组mipmappedArray，该数组必须是通过先前调用cudaMallocMipmappedArray()返回的。如果devPtr为0，则不执行任何操作。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaFree, cudaMallocArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, cuMipmappedArrayDestroy

__host__ cudaError_t cudaGetMipmappedArrayLevel ( cudaArray_t* levelArray, cudaMipmappedArray_const_t mipmappedArray, unsigned int level )

获取CUDA mipmapped数组的mipmap层级。

参数

levelArray: - Returned mipmap level CUDA array
mipmappedArray: - CUDA mipmapped array
level: - Mipmap level

cudaSuccess, cudaErrorInvalidValue cudaErrorInvalidResourceHandle

描述

在*levelArray中返回一个表示CUDA mipmapped数组mipmappedArray单个mipmap级别的CUDA数组。

如果level大于此mipmapped数组中的最大层级数，将返回cudaErrorInvalidValue。

如果mipmappedArray为NULL，则返回cudaErrorInvalidResourceHandle。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc3D, cudaMalloc, cudaMallocPitch, cudaFree, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, make_cudaExtent, cuMipmappedArrayGetLevel

__host__ cudaError_t cudaGetSymbolAddress ( void** devPtr, const void* symbol )

查找与CUDA符号关联的地址。

参数

devPtr: - Return device pointer associated with symbol
symbol: - Device symbol address

cudaSuccess, cudaErrorInvalidSymbol, cudaErrorNoKernelImageForDevice

描述

返回设备上符号symbol在*devPtr中的地址。symbol是位于全局或常量内存空间中的变量。如果找不到symbol，或者symbol未在全局或常量内存空间中声明，则*devPtr保持不变，并返回错误cudaErrorInvalidSymbol。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGetSymbolAddress ( C++ API), cudaGetSymbolSize ( C API), cuModuleGetGlobal

__host__ cudaError_t cudaGetSymbolSize ( size_t* size, const void* symbol )

查找与CUDA符号关联的对象的大小。

参数

size: - Size of object associated with symbol
symbol: - Device symbol address

cudaSuccess, cudaErrorInvalidSymbol, cudaErrorNoKernelImageForDevice

描述

返回符号symbol的大小到*size中。symbol是位于全局或常量内存空间中的变量。如果找不到symbol，或者symbol未在全局或常量内存空间中声明，则*size保持不变并返回错误cudaErrorInvalidSymbol。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGetSymbolAddress ( C API), cudaGetSymbolSize ( C++ API), cuModuleGetGlobal

__host__ cudaError_t cudaHostAlloc ( void** pHost, size_t size, unsigned int flags )

在主机上分配页锁定内存。

参数

pHost: - Device pointer to allocated memory
size: - Requested allocation size in bytes
flags: - Requested properties of allocated memory

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

分配size字节的页锁定主机内存，该内存可被设备直接访问。驱动程序会跟踪通过此函数分配的虚拟内存范围，并自动加速对cudaMemcpy()等函数的调用。由于设备可以直接访问该内存，其读写带宽远高于通过malloc()等函数分配的可分页内存。但分配过多的固定内存可能会降低系统性能，因为这会减少系统可用于分页的内存量。因此，建议谨慎使用此函数，主要用于分配主机与设备间数据交换的暂存区域。

flags 参数用于指定影响分配的不同选项，如下所示。

cudaHostAllocDefault: 该标志的值定义为0，会使cudaHostAlloc()模拟cudaMallocHost()的行为。
cudaHostAllocPortable: 此调用返回的内存将被所有CUDA上下文视为固定内存，而不仅仅是执行分配的那个上下文。
cudaHostAllocMapped: 将分配的内存映射到CUDA地址空间。可以通过调用cudaHostGetDevicePointer()获取该内存的设备指针。
cudaHostAllocWriteCombined: 将内存分配为写合并(WC)模式。在某些系统配置下，WC内存能更快地通过PCI Express总线传输，但大多数CPU无法高效读取。对于CPU写入并通过映射固定内存或主机到设备传输由设备读取的缓冲区，WC内存是一个很好的选择。

所有这些标志彼此之间是正交的：开发者可以不受限制地分配具有可移植性、映射和/或写合并特性的内存。

为了使cudaHostAllocMapped标志生效，CUDA上下文必须支持cudaDeviceMapHost标志，这可以通过cudaGetDeviceFlags()进行检查。对于通过运行时API创建的上下文，cudaDeviceMapHost标志会被隐式设置。

对于不支持映射固定内存的设备，可以在CUDA上下文中指定cudaHostAllocMapped标志。由于内存可能通过cudaHostAllocPortable标志映射到其他CUDA上下文中，因此失败会延迟到cudaHostGetDevicePointer()。

通过此函数分配的内存必须使用cudaFreeHost()释放。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaSetDeviceFlags, cudaMallocHost ( C API), cudaFreeHost, cudaGetDeviceFlags, cuMemHostAlloc

__host__ cudaError_t cudaHostGetDevicePointer ( void** pDevice, void* pHost, unsigned int flags )

返回由cudaHostAlloc分配或通过cudaHostRegister注册的映射主机内存的设备指针。

参数

pDevice: - Returned device pointer for mapped memory
pHost: - Requested host pointer mapping
flags: - Flags for extensions (must be 0 for now)

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

返回与由cudaHostAlloc()分配的或由cudaHostRegister()注册的映射固定主机缓冲区对应的设备指针。

cudaHostGetDevicePointer() 函数将会失败，如果在延迟上下文创建之前未指定cudaDeviceMapHost标志，或者在不支持映射固定内存的设备上调用该函数。

对于设备属性cudaDevAttrCanUseHostPointerForRegisteredMem值为非零的设备，还可以使用主机指针pHost从设备访问该内存。cudaHostGetDevicePointer()返回的设备指针可能与原始主机指针pHost匹配也可能不匹配，这取决于应用程序可见的设备。如果应用程序可见的所有设备的该属性值均为非零，则cudaHostGetDevicePointer()返回的设备指针将与原始指针pHost匹配。如果应用程序可见的任何设备该属性值为零，则cudaHostGetDevicePointer()返回的设备指针不会匹配原始主机指针pHost，但只要启用了统一虚拟寻址，该指针就适用于所有设备。在此类系统中，对于该属性值为非零的设备，使用任一指针访问内存都是有效的。但请注意，此类设备应仅使用两个指针中的一个来访问内存，而不是同时使用两者。

flags 为未来版本预留。目前必须设置为0。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaSetDeviceFlags, cudaHostAlloc, cuMemHostGetDevicePointer

__host__ cudaError_t cudaHostGetFlags ( unsigned int* pFlags, void* pHost )

返回用于分配由cudaHostAlloc分配的固定主机内存的标志。

参数

pFlags: - Returned flags word
pHost: - Host pointer

cudaSuccess, cudaErrorInvalidValue

描述

cudaHostGetFlags() 如果输入的指针不在由 cudaHostAlloc() 分配的地址范围内，将会执行失败。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaHostAlloc, cuMemHostGetFlags

__host__ cudaError_t cudaHostRegister ( void* ptr, size_t size, unsigned int flags )

注册现有的主机内存范围以供CUDA使用。

参数

ptr: - Host pointer to memory to page-lock
size: - Size in bytes of the address range to page-lock in bytes
flags: - Flags for allocation request

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation, cudaErrorHostMemoryAlreadyRegistered, cudaErrorNotSupported

描述

将ptr和size指定的内存范围进行页锁定，并根据flags参数映射到指定设备。该内存范围会被加入与cudaHostAlloc()相同的跟踪机制，以自动加速cudaMemcpy()等函数的调用。由于设备可直接访问该内存，其读写带宽远高于未注册的可分页内存。但锁定过多内存可能会降低系统性能，因为这会减少系统可用于分页的内存量。因此，建议谨慎使用此功能，主要用于注册主机与设备间数据交换的暂存区域。

在pageableMemoryAccessUsesHostPageTables为true的系统上，cudaHostRegister不会锁定ptr指定的内存范围，而只会填充未填充的页面。

cudaHostRegister 仅在具有非零设备属性 cudaDevAttrHostRegisterSupported 的I/O一致性设备上受支持。

flags 参数用于指定影响分配的不同选项，如下所示。

cudaHostRegisterDefault: 在具有统一虚拟地址的系统上，内存将同时被映射且可移植。在不支持统一虚拟地址的系统上，内存既不会被映射也不具备可移植性。

cudaHostRegisterPortable: 此调用返回的内存将被所有CUDA上下文视为固定内存，而不仅限于执行分配的上下文。

cudaHostRegisterMapped: 将分配的内存映射到CUDA地址空间。可以通过调用cudaHostGetDevicePointer()获取该内存的设备指针。

cudaHostRegisterIoMemory: 传入的内存指针被视为指向某些内存映射的I/O空间（例如属于第三方PCIe设备），它将被标记为非缓存一致且连续的。

cudaHostRegisterReadOnly: 传入的内存指针将被视为指向设备只读内存。在不支持cudaDevAttrPageableMemoryAccessUsesHostPageTables的平台上，该标志用于将CPU映射的内存注册为只读。可通过设备属性cudaDevAttrHostRegisterReadOnlySupported查询是否支持此标志。若在当前上下文关联的设备未设置此属性时使用该标志，将导致cudaHostRegister返回cudaErrorNotSupported错误。

所有这些标志彼此之间是正交的：开发者可以对可移植或映射的内存进行页锁定，没有任何限制。

CUDA上下文必须已使用cudaMapHost标志创建，才能使cudaHostRegisterMapped标志生效。

对于不支持映射固定内存的设备，可以在CUDA上下文中指定cudaHostRegisterMapped标志。由于内存可能通过cudaHostRegisterPortable标志映射到其他CUDA上下文中，因此失败会延迟到cudaHostGetDevicePointer()。

对于设备属性cudaDevAttrCanUseHostPointerForRegisteredMem值非零的设备，还可以使用主机指针ptr从设备访问内存。cudaHostGetDevicePointer()返回的设备指针可能与原始主机指针ptr匹配，也可能不匹配，这取决于应用程序可见的设备。如果应用程序可见的所有设备的该属性值都非零，则cudaHostGetDevicePointer()返回的设备指针将与原始指针ptr匹配。如果应用程序可见的任何设备该属性值为零，则cudaHostGetDevicePointer()返回的设备指针不会匹配原始主机指针ptr，但只要启用了统一虚拟寻址，该指针就适用于所有设备。在此类系统中，对于该属性值非零的设备，使用任一指针访问内存都是有效的。但需要注意的是，此类设备应仅使用两个指针中的一个来访问内存，而不是同时使用两者。

通过此函数锁定的内存页必须使用cudaHostUnregister()进行注销。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaHostUnregister, cudaHostGetFlags, cudaHostGetDevicePointer, cuMemHostRegister

__host__ cudaError_t cudaHostUnregister ( void* ptr )

注销之前通过cudaHostRegister注册的内存范围。

参数

ptr: - Host pointer to memory to unregister

cudaSuccess, cudaErrorInvalidValue, cudaErrorHostMemoryNotRegistered

描述

解除映射基地址由ptr指定的内存范围，并使其再次可分页。

基地址必须与指定给cudaHostRegister()的地址相同。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaHostUnregister, cuMemHostUnregister

__host__ __device__ cudaError_t cudaMalloc ( void** devPtr, size_t size )

在设备上分配内存。

参数

devPtr: - Pointer to allocated device memory
size: - Requested allocation size in bytes

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

在设备上分配size字节的线性内存，并在*devPtr中返回指向已分配内存的指针。分配的内存已针对任何类型的变量进行适当对齐。内存不会被清除。 cudaMalloc()在失败时返回cudaErrorMemoryAllocation。

设备版本的cudaFree不能用于通过主机API分配的*devPtr，反之亦然。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMallocPitch, cudaFree, cudaMallocArray, cudaFreeArray, cudaMalloc3D, cudaMalloc3DArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, cuMemAlloc

__host__ cudaError_t cudaMalloc3D ( cudaPitchedPtr* pitchedDevPtr, cudaExtent extent )

在设备上分配逻辑1D、2D或3D内存对象。

参数

pitchedDevPtr: - Pointer to allocated pitched device memory
extent: - Requested allocation size (width field in bytes)

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

在设备上分配至少width * height * depth字节的线性内存，并返回一个cudaPitchedPtr，其中ptr是指向所分配内存的指针。该函数可能会对分配进行填充以确保满足硬件对齐要求。在pitchedDevPtr的pitch字段中返回的间距是分配的宽度（以字节为单位）。

返回的cudaPitchedPtr包含额外字段xsize和ysize，表示分配的逻辑宽度和高度，这些等同于程序员在分配时提供的width和heightextent参数。

对于2D和3D对象的内存分配，强烈建议程序员使用cudaMalloc3D()或cudaMallocPitch()进行分配。由于硬件的对齐限制，如果应用程序将执行涉及2D或3D对象（无论是线性内存还是CUDA数组）的内存复制操作，这一点尤为重要。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMallocPitch, cudaFree, cudaMemcpy3D, cudaMemset3D, cudaMalloc3DArray, cudaMallocArray, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, make_cudaPitchedPtr, make_cudaExtent, cuMemAllocPitch

__host__ cudaError_t cudaMalloc3DArray ( cudaArray_t* array, const cudaChannelFormatDesc* desc, cudaExtent extent, unsigned int flags = 0 )

在设备上分配一个数组。

参数

array: - Pointer to allocated array in device memory
desc: - Requested channel format
extent: - Requested allocation size (width field in elements)
flags: - Flags for extensions

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

根据cudaChannelFormatDesc结构体desc分配一个CUDA数组，并在*array中返回新CUDA数组的句柄。

cudaChannelFormatDesc的定义如下：

‎    struct cudaChannelFormatDesc {
              int x, y, z, w;
              enum cudaChannelFormatKind 
                  f;
          };

where cudaChannelFormatKind is one of cudaChannelFormatKindSigned, cudaChannelFormatKindUnsigned, or cudaChannelFormatKindFloat.

cudaMalloc3DArray() 可以分配以下内容：

如果高度和深度范围均为零，则分配一个一维数组。
如果深度范围为零，则分配一个二维数组。
如果所有三个维度范围都非零，则会分配一个3D数组。
如果仅高度范围为0且设置了cudaArrayLayered标志，则会分配一个一维分层CUDA数组。每个层都是一个一维数组。层数由深度范围决定。
如果所有三个维度范围均非零且设置了cudaArrayLayered标志，则会分配一个2D分层CUDA数组。每个层都是一个2D数组，层数由深度范围决定。
如果所有三个维度均非零且设置了cudaArrayCubemap标志，则会分配一个立方体贴图CUDA数组。宽度必须等于高度，且深度必须为六。立方体贴图是一种特殊的二维分层CUDA数组，其中六个层代表立方体的六个面。内存中六个层的顺序与cudaGraphicsCubeFace中列出的顺序相同。
如果所有三个维度均非零，并且同时设置了cudaArrayCubemap和cudaArrayLayered标志，则会分配一个立方体贴图层叠的CUDA数组。宽度必须等于高度，深度必须是六的倍数。立方体贴图层叠的CUDA数组是一种特殊类型的2D分层CUDA数组，由一系列立方体贴图组成。前六层代表第一个立方体贴图，接下来的六层构成第二个立方体贴图，依此类推。

flags 参数用于指定影响分配的不同选项，如下所示。

cudaArrayDefault: 该标志的值定义为0，表示默认的数组分配方式
cudaArrayLayered: 分配一个分层CUDA数组，深度范围表示层数
cudaArrayCubemap: 分配一个立方体贴图CUDA数组。宽度必须等于高度，深度必须为六。如果同时设置了cudaArrayLayered标志，则深度必须是六的倍数。
cudaArraySurfaceLoadStore: 分配一个可通过表面引用进行读写操作的CUDA数组。
cudaArrayTextureGather: 此标志表示将在CUDA数组上执行纹理收集操作。纹理收集只能在2D CUDA数组上执行。
cudaArraySparse: 分配一个没有物理后备内存的CUDA数组。该稀疏数组中的子区域后续可以通过调用cuMemMapArrayAsync映射到物理内存分配上。此标志仅能用于创建2D、3D或2D分层稀疏CUDA数组。物理后备内存必须通过cuMemCreate进行分配。
cudaArrayDeferredMapping: 分配一个没有物理后备内存的CUDA数组。之后可以通过调用cuMemMapArrayAsync将整个数组映射到物理内存分配上。物理后备内存必须通过cuMemCreate进行分配。

宽度、高度和深度范围必须满足下表中列出的特定尺寸要求。所有数值均以元素为单位指定。

请注意，如果设置了cudaArrayTextureGather标志，2D CUDA数组会有不同的尺寸要求。在这种情况下，(宽度, 高度, 深度)的有效范围是((1,maxTexture2DGather[0]), (1,maxTexture2DGather[1]), 0)。

CUDA数组类型	必须始终满足的有效范围 {(以元素为单位的宽度范围), (高度范围), (深度范围)}	设置cudaArraySurfaceLoadStore时的有效范围 {(以元素为单位的宽度范围), (高度范围), (深度范围)}
1D	{ (1,maxTexture1D), 0, 0 }	{ (1,maxSurface1D), 0, 0 }
2D	{ (1,maxTexture2D[0]), (1,maxTexture2D[1]), 0 }	{ (1,maxSurface2D[0]), (1,maxSurface2D[1]), 0 }
3D	{ (1,maxTexture3D[0]), (1,maxTexture3D[1]), (1,maxTexture3D[2]) } 或 { (1,maxTexture3DAlt[0]), (1,maxTexture3DAlt[1]), (1,maxTexture3DAlt[2]) }	{ (1,maxSurface3D[0]), (1,maxSurface3D[1]), (1,maxSurface3D[2]) }
一维分层	{ (1,maxTexture1DLayered[0]), 0, (1,maxTexture1DLayered[1]) }	{ (1,maxSurface1DLayered[0]), 0, (1,maxSurface1DLayered[1]) }
2D分层	{ (1,maxTexture2DLayered[0]), (1,maxTexture2DLayered[1]), (1,maxTexture2DLayered[2]) }	{ (1,maxSurface2DLayered[0]), (1,maxSurface2DLayered[1]), (1,maxSurface2DLayered[2]) }
立方体贴图	{ (1,maxTextureCubemap), (1,maxTextureCubemap), 6 }	{ (1,maxSurfaceCubemap), (1,maxSurfaceCubemap), 6 }
立方体贴图分层	{ (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[1]) }	{ (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[1]) }

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc3D, cudaMalloc, cudaMallocPitch, cudaFree, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, make_cudaExtent, cuArray3DCreate

__host__ cudaError_t cudaMallocArray ( cudaArray_t* array, const cudaChannelFormatDesc* desc, size_t width, size_t height = 0, unsigned int flags = 0 )

在设备上分配一个数组。

参数

array: - Pointer to allocated array in device memory
desc: - Requested channel format
width: - Requested array allocation width
height: - Requested array allocation height
flags: - Requested properties of allocated array

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

根据cudaChannelFormatDesc结构体desc分配一个CUDA数组，并在*array中返回新CUDA数组的句柄。

cudaChannelFormatDesc的定义如下：

‎    struct cudaChannelFormatDesc {
              int x, y, z, w;
          enum cudaChannelFormatKind 
                  f;
          };

where cudaChannelFormatKind is one of cudaChannelFormatKindSigned, cudaChannelFormatKindUnsigned, or cudaChannelFormatKindFloat.

flags 参数用于指定影响分配的不同选项，如下所示。

cudaArrayDefault: 该标志的值定义为0，表示默认的数组分配方式
cudaArraySurfaceLoadStore: 分配一个可以使用表面引用进行读取或写入的数组
cudaArrayTextureGather: 该标志表示将在数组上执行纹理收集操作。
cudaArraySparse: 分配一个没有物理后备内存的CUDA数组。该稀疏数组中的子区域后续可以通过调用cuMemMapArrayAsync映射到物理内存分配上。物理后备内存必须通过cuMemCreate进行分配。
cudaArrayDeferredMapping: 分配一个没有物理后备内存的CUDA数组。之后可以通过调用cuMemMapArrayAsync将整个数组映射到物理内存分配上。物理后备内存必须通过cuMemCreate进行分配。

width 和 height 必须满足特定的大小要求。详情请参阅 cudaMalloc3DArray()。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaFree, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaMalloc3D, cudaMalloc3DArray, cudaHostAlloc, cuArrayCreate

__host__ cudaError_t cudaMallocHost ( void** ptr, size_t size )

在主机上分配页锁定内存。

参数

ptr: - Pointer to allocated host memory
size: - Requested allocation size in bytes

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

分配size字节的主机内存，该内存被页锁定且设备可访问。驱动程序会跟踪通过此函数分配的虚拟内存范围，并自动加速对cudaMemcpy*()等函数的调用。由于设备可以直接访问该内存，因此其读写带宽远高于通过malloc()等函数获得的可分页内存。

在pageableMemoryAccessUsesHostPageTables为true的系统上，cudaMallocHost可能不会对分配的内存进行页锁定。

使用cudaMallocHost()锁定过多内存可能会降低系统性能，因为它减少了系统可用于分页的内存容量。因此，该函数最好谨慎使用，仅用于分配主机与设备之间数据交换的暂存区域。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaMallocPitch, cudaMallocArray, cudaMalloc3D, cudaMalloc3DArray, cudaHostAlloc, cudaFree, cudaFreeArray, cudaMallocHost ( C++ API), cudaFreeHost, cudaHostAlloc, cuMemAllocHost

__host__ cudaError_t cudaMallocManaged ( void** devPtr, size_t size, unsigned int flags = cudaMemAttachGlobal )

分配将由统一内存系统自动管理的内存。

参数

devPtr: - Pointer to allocated device memory
size: - Requested allocation size in bytes
flags: - Must be either cudaMemAttachGlobal or cudaMemAttachHost (defaults to cudaMemAttachGlobal)

cudaSuccess, cudaErrorMemoryAllocation, cudaErrorNotSupported, cudaErrorInvalidValue

描述

在设备上分配size字节的托管内存，并通过*devPtr返回指向已分配内存的指针。如果设备不支持分配托管内存，则返回cudaErrorNotSupported。可以使用设备属性cudaDevAttrManagedMemory查询对托管内存的支持情况。分配的内存会进行适当对齐，适合任何类型的变量。内存不会被清零。如果size为0，cudaMallocManaged将返回cudaErrorInvalidValue。该指针在CPU和系统中所有支持托管内存的GPU上均有效。对此指针的所有访问都必须遵循统一内存编程模型。

flags 指定此内存分配的默认流关联。flags 必须是 cudaMemAttachGlobal 或 cudaMemAttachHost 之一。flags 的默认值为 cudaMemAttachGlobal。如果指定了 cudaMemAttachGlobal，则此内存可从任何设备上的任何流访问。如果指定了 cudaMemAttachHost，则不应从设备属性 cudaDevAttrConcurrentManagedAccess 值为零的设备访问该分配；需要显式调用 cudaStreamAttachMemAsync 才能在此类设备上启用访问。

如果之后通过cudaStreamAttachMemAsync将关联更改为单个流，则在销毁该流时，会恢复cudaMallocManaged期间指定的默认关联。对于__managed__变量，默认关联始终是cudaMemAttachGlobal。请注意，销毁流是一个异步操作，因此，在流中的所有工作完成之前，不会发生默认关联的更改。

使用cudaMallocManaged分配的内存应当通过cudaFree释放。

对于设备属性cudaDevAttrConcurrentManagedAccess值为非零的GPU，可以实现设备内存超额订阅。在这类GPU上，统一内存驱动程序可能随时将托管内存从设备内存驱逐到主机内存，以便为其他分配腾出空间。

在所有GPU设备的cudaDevAttrConcurrentManagedAccess属性值非零的系统中，当此API返回时托管内存可能尚未分配，而是在访问时才会分配。在此类系统中，托管内存可以随时迁移到任何处理器的内存中。统一内存驱动程序将采用启发式方法来尽可能保持数据局部性并避免过多的页面错误。应用程序还可以通过cudaMemAdvise向驱动程序提供内存使用模式的指导。应用程序也可以通过cudaMemPrefetchAsync显式地将内存迁移到目标处理器的内存中。

在一个多GPU系统中，如果所有GPU的设备属性cudaDevAttrConcurrentManagedAccess值均为零，且所有GPU之间都支持点对点访问，那么托管内存的物理存储将在调用cudaMallocManaged时所在的活跃GPU上创建。所有其他GPU将通过PCIe总线上的点对点映射以较低带宽访问该数据。统一内存驱动程序不会在这些GPU之间迁移内存。

在多GPU系统中，如果并非所有GPU都支持彼此之间的点对点通信，并且其中至少一个GPU的设备属性cudaDevAttrConcurrentManagedAccess值为零时，托管内存物理存储位置的选择将取决于系统。

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 cudaDevAttrConcurrentManagedAccess. 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.
在Windows系统上，物理存储始终创建在'零拷贝'或主机内存中。所有GPU将通过PCIe总线以降低的带宽引用数据。在这种情况下，建议使用环境变量CUDA_VISIBLE_DEVICES来限制CUDA仅使用那些支持点对点传输的GPU。或者，用户也可以将CUDA_MANAGED_FORCE_DEVICE_ALLOC设置为非零值，强制驱动程序始终使用设备内存作为物理存储。当此环境变量设置为非零值时，该进程中使用且支持托管内存的所有设备必须彼此具备点对点兼容性。如果使用了支持托管内存的设备，但该设备与该进程先前使用的其他支持托管内存的设备不具备点对点兼容性，即使已对这些设备调用cudaDeviceReset，也将返回错误cudaErrorInvalidDevice。这些环境变量在CUDA编程指南的"CUDA环境变量"章节中有详细说明。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMallocPitch, cudaFree, cudaMallocArray, cudaFreeArray, cudaMalloc3D, cudaMalloc3DArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, cudaDeviceGetAttribute, cudaStreamAttachMemAsync, cuMemAllocManaged

__host__ cudaError_t cudaMallocMipmappedArray ( cudaMipmappedArray_t* mipmappedArray, const cudaChannelFormatDesc* desc, cudaExtent extent, unsigned int numLevels, unsigned int flags = 0 )

在设备上分配一个mipmapped数组。

参数

mipmappedArray: - Pointer to allocated mipmapped array in device memory
desc: - Requested channel format
extent: - Requested allocation size (width field in elements)
numLevels: - Number of mipmap levels to allocate
flags: - Flags for extensions

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

根据cudaChannelFormatDesc结构体desc分配一个CUDA mipmapped数组，并在*mipmappedArray中返回新CUDA mipmapped数组的句柄。numLevels指定要分配的mipmap级别数量。该值会被限制在[1, 1 + floor(log2(max(width, height, depth)))]范围内。

cudaChannelFormatDesc的定义如下：

‎    struct cudaChannelFormatDesc {
              int x, y, z, w;
              enum cudaChannelFormatKind 
                  f;
          };

where cudaChannelFormatKind is one of cudaChannelFormatKindSigned, cudaChannelFormatKindUnsigned, or cudaChannelFormatKindFloat.

cudaMallocMipmappedArray() 可以分配以下内容：

如果高度和深度范围均为零，则分配一个一维mipmapped数组。
如果深度范围为零，则分配一个2D mipmapped数组。
如果三个维度范围均不为零，则分配一个3D mipmapped数组。
如果仅高度范围为零且设置了cudaArrayLayered标志，则会分配一个一维分层CUDA mipmapped数组。每个层都是一个一维mipmapped数组。层数由深度范围决定。
如果所有三个维度均非零且设置了cudaArrayLayered标志，则会分配一个2D分层CUDA mipmapped数组。每个层都是一个2D mipmapped数组。层数由深度维度决定。
如果三个维度均非零且设置了cudaArrayCubemap标志，则会分配一个立方体贴图CUDA多级渐远纹理数组。宽度必须等于高度，且深度必须为六。内存中六个图层的顺序与cudaGraphicsCubeFace中列出的顺序相同。
当所有三个维度都不为零，并且同时设置了cudaArrayCubemap和cudaArrayLayered标志时，将分配一个立方体贴图分层的CUDA mipmapped数组。宽度必须等于高度，深度必须是六的倍数。立方体贴图分层的CUDA mipmapped数组是一种特殊类型的2D分层CUDA mipmapped数组，由一系列立方体贴图mipmapped数组组成。前六层表示第一个立方体贴图mipmapped数组，接下来的六层构成第二个立方体贴图mipmapped数组，依此类推。

flags 参数用于指定影响分配的不同选项，如下所示。

cudaArrayDefault: 该标志的值定义为0，用于提供默认的mipmapped数组分配
cudaArrayLayered: 分配一个分层的CUDA mipmapped数组，深度范围表示层数
cudaArrayCubemap: 分配一个立方体贴图CUDA mipmapped数组。宽度必须等于高度，且深度必须为六。如果同时设置了cudaArrayLayered标志，则深度必须是六的倍数。
cudaArraySurfaceLoadStore: 此标志表示将使用表面引用对CUDA多级渐远纹理数组的各个mipmap层级进行读写操作。
cudaArrayTextureGather: 此标志表示将在CUDA数组上执行纹理收集操作。纹理收集只能在2D CUDA mipmapped数组上执行，并且收集操作仅在最高细节的mipmap层级进行。
cudaArraySparse: 分配一个没有物理后备内存的CUDA mipmapped数组。该稀疏数组中的子区域后续可以通过调用cuMemMapArrayAsync映射到物理内存分配上。此标志仅能用于创建2D、3D或2D分层稀疏CUDA mipmapped数组。物理后备内存必须通过cuMemCreate进行分配。
cudaArrayDeferredMapping: 分配一个没有物理后备内存的CUDA mipmapped数组。之后可以通过调用cuMemMapArrayAsync将整个数组映射到物理内存分配上。物理后备内存必须通过cuMemCreate进行分配。

宽度、高度和深度范围必须满足下表中列出的特定尺寸要求。所有数值均以元素为单位指定。

CUDA数组类型	必须始终满足的有效范围{(以元素为单位的宽度范围), (高度范围), (深度范围)}	设置cudaArraySurfaceLoadStore时的有效范围{(以元素为单位的宽度范围), (高度范围), (深度范围)}
1D	{ (1,maxTexture1DMipmap), 0, 0 }	{ (1,maxSurface1D), 0, 0 }
2D	{ (1,maxTexture2DMipmap[0]), (1,maxTexture2DMipmap[1]), 0 }	{ (1,maxSurface2D[0]), (1,maxSurface2D[1]), 0 }
3D	{ (1,maxTexture3D[0]), (1,maxTexture3D[1]), (1,maxTexture3D[2]) } 或 { (1,maxTexture3DAlt[0]), (1,maxTexture3DAlt[1]), (1,maxTexture3DAlt[2]) }	{ (1,maxSurface3D[0]), (1,maxSurface3D[1]), (1,maxSurface3D[2]) }
一维分层	{ (1,maxTexture1DLayered[0]), 0, (1,maxTexture1DLayered[1]) }	{ (1,maxSurface1DLayered[0]), 0, (1,maxSurface1DLayered[1]) }
2D分层	{ (1,maxTexture2DLayered[0]), (1,maxTexture2DLayered[1]), (1,maxTexture2DLayered[2]) }	{ (1,maxSurface2DLayered[0]), (1,maxSurface2DLayered[1]), (1,maxSurface2DLayered[2]) }
立方体贴图	{ (1,maxTextureCubemap), (1,maxTextureCubemap), 6 }	{ (1,maxSurfaceCubemap), (1,maxSurfaceCubemap), 6 }
立方体贴图分层	{ (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[0]), (1,maxTextureCubemapLayered[1]) }	{ (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[0]), (1,maxSurfaceCubemapLayered[1]) }

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc3D, cudaMalloc, cudaMallocPitch, cudaFree, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaHostAlloc, make_cudaExtent, cuMipmappedArrayCreate

__host__ cudaError_t cudaMallocPitch ( void** devPtr, size_t* pitch, size_t width, size_t height )

在设备上分配倾斜内存。

参数

devPtr: - Pointer to allocated pitched device memory
pitch: - Pitch for allocation
width: - Requested pitched allocation width (in bytes)
height: - Requested pitched allocation height

cudaSuccess, cudaErrorInvalidValue, cudaErrorMemoryAllocation

描述

在设备上分配至少width（以字节为单位）乘以height字节的线性内存，并在*devPtr中返回指向已分配内存的指针。该函数可能会对分配进行填充，以确保当地址逐行更新时，任何给定行中的对应指针将继续满足合并对齐要求。cudaMallocPitch()在*pitch中返回的间距是分配的宽度（以字节为单位）。pitch的预期用途是作为分配的单独参数，用于计算二维数组中的地址。给定类型为T的数组元素的行和列，地址计算方式为：

‎    T* pElement = (T*)((char*)BaseAddress + Row * pitch) + Column;

对于二维数组的内存分配，建议程序员考虑使用cudaMallocPitch()进行跨距分配。由于硬件中的跨距对齐限制，如果应用程序需要在设备内存的不同区域（无论是线性内存还是CUDA数组）之间执行二维内存拷贝操作，这一点尤为重要。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc, cudaFree, cudaMallocArray, cudaFreeArray, cudaMallocHost ( C API), cudaFreeHost, cudaMalloc3D, cudaMalloc3DArray, cudaHostAlloc, cuMemAllocPitch

__host__ cudaError_t cudaMemAdvise ( const void* devPtr, size_t count, cudaMemoryAdvise advice, int device )

提供关于给定内存范围使用情况的建议。

参数

devPtr: - Pointer to memory to set the advice for
count: - Size in bytes of the memory range
advice: - Advice to be applied for the specified memory range
device: - Device to apply the advice for

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

向统一内存子系统提供关于从devPtr开始、大小为count字节的内存范围使用模式的建议。在应用建议之前，内存范围的起始地址和结束地址将分别向下和向上取整以对齐CPU页面大小。该内存范围必须指向通过cudaMallocManaged分配的托管内存或通过__managed__变量声明的内存。该内存范围也可以指向系统分配的可分页内存，前提是它表示一个有效的、主机可访问的内存区域，并且满足下面概述的advice所施加的所有额外约束。指定无效的系统分配可分页内存范围将返回错误。

advice 参数可以接受以下值：

cudaMemAdviseSetReadMostly: 表示该数据将主要用于读取而仅偶尔写入。任何处理器对该区域的读取访问都会在该处理器内存中创建至少被访问页面的只读副本。此外，如果对该区域调用cudaMemPrefetchAsync，将在目标处理器上创建数据的只读副本。如果任何处理器写入该区域，除发生写入的副本外，相应页面的所有其他副本都将失效。此建议将忽略device参数。请注意，要实现页面读取复制，访问处理器必须是CPU或具有设备属性cudaDevAttrConcurrentManagedAccess非零值的GPU。此外，如果在未设置设备属性cudaDevAttrConcurrentManagedAccess的设备上创建上下文，则在这些上下文全部销毁之前不会发生读取复制。如果内存区域引用有效的系统分配可分页内存，则访问设备必须具有设备属性cudaDevAttrPageableMemoryAccess的非零值才能在该设备上创建只读副本。但需注意，如果访问设备还具有设备属性cudaDevAttrPageableMemoryAccessUsesHostPageTables的非零值，则设置此建议不会在该设备访问此内存区域时创建只读副本。

cudaMemAdviceUnsetReadMostly: 撤销cudaMemAdviceReadMostly的效果，并阻止统一内存驱动程序尝试在该内存范围上进行启发式读取复制。任何读取复制的数据副本将被合并为单个副本。如果页面有首选位置且其中一个读取复制的副本驻留在该位置，则合并后的副本将位于首选位置。否则，所选位置是任意的。

cudaMemAdviseSetPreferredLocation: 该建议将数据的首选位置设置为属于device的内存。为device传入cudaCpuDeviceId会将首选位置设为主机内存。如果device是GPU，则该设备必须具有设备属性cudaDevAttrConcurrentManagedAccess的非零值。设置首选位置不会立即导致数据迁移到该位置，而是在该内存区域发生故障时指导迁移策略。如果数据已在其首选位置，且故障处理器无需迁移数据即可建立映射，则将避免数据迁移。反之，如果数据不在其首选位置或无法建立直接映射，则数据将被迁移到访问它的处理器。需注意设置首选位置不会阻止通过cudaMemPrefetchAsync完成的数据预取。设置首选位置可能覆盖统一内存驱动中的页面抖动检测和解决逻辑。通常，如果检测到页面在主机与设备内存间持续抖动，统一内存驱动最终可能将该页面固定到主机内存。但若将首选位置设为设备内存，则该页面将无限期持续抖动。如果在该内存区域或其任何子集上还设置了cudaMemAdviseSetReadMostly，则与该建议相关的策略将覆盖本建议的策略，除非如cudaMemAdviseSetReadMostly建议描述所述，来自device的读取访问不会在该设备上创建只读副本。如果内存区域引用有效的系统分配可分页内存，则device必须具有设备属性cudaDevAttrPageableMemoryAccess的非零值。

cudaMemAdviseUnsetPreferredLocation: 撤销cudaMemAdviseSetPreferredLocation的效果并将首选位置更改为无。

cudaMemAdviseSetAccessedBy: 该建议表示数据将被device访问。传入cudaCpuDeviceId作为device将为CPU设置建议。如果device是GPU，则设备属性cudaDevAttrConcurrentManagedAccess必须非零。该建议不会导致数据迁移，本身也不会影响数据的位置。相反，只要数据位置允许建立映射，它就会使数据始终映射到指定处理器的页表中。如果数据因任何原因发生迁移，映射也会相应更新。在数据局部性不重要但需要避免缺页错误的场景中推荐使用此建议。例如考虑一个启用了点对点访问的多GPU系统，其中一个GPU上的数据偶尔会被对等GPU访问。在此类场景中，将数据迁移到其他GPU并不重要，因为访问不频繁且迁移开销可能过高。但预防缺页错误仍有助于提高性能，因此预先建立映射很有用。请注意，当CPU访问此数据时，数据可能会迁移到主机内存，因为CPU通常无法直接访问设备内存。任何为此数据设置了cudaMemAdviceSetAccessedBy标志的GPU现在都会更新其映射以指向主机内存中的页面。如果在此内存区域或其任何子集上还设置了cudaMemAdviseSetReadMostly，则与该建议相关的策略将覆盖本建议的策略。此外，如果此内存区域或其任何子集的优选位置也是device，则与cudaMemAdviseSetPreferredLocation相关的策略将覆盖本建议的策略。如果内存区域引用有效的系统分配可分页内存，则device必须具有非零值的设备属性cudaDevAttrPageableMemoryAccess。此外，如果device的设备属性cudaDevAttrPageableMemoryAccessUsesHostPageTables具有非零值，则此调用无效。

cudaMemAdviseUnsetAccessedBy: 撤销cudaMemAdviseSetAccessedBy的效果。来自device的任何数据映射可能随时被移除，导致访问产生非致命页面错误。如果内存区域引用有效的系统分配可分页内存，则device必须对设备属性cudaDevAttrPageableMemoryAccess具有非零值。此外，如果device对设备属性cudaDevAttrPageableMemoryAccessUsesHostPageTables具有非零值，则此调用无效。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpy3DPeerAsync, cudaMemPrefetchAsync, cuMemAdvise

__host__ cudaError_t cudaMemAdvise_v2 ( const void* devPtr, size_t count, cudaMemoryAdvise advice, cudaMemLocation location )

提供关于给定内存范围使用情况的建议。

参数

devPtr: - Pointer to memory to set the advice for
count: - Size in bytes of the memory range
advice: - Advice to be applied for the specified memory range
location: - location to apply the advice for

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

advice 参数可以接受以下值：

cudaMemAdviseSetReadMostly: 表示该数据将主要用于读取而偶尔写入。任何处理器对该区域的读取访问都会在该处理器内存中创建至少被访问页面的只读副本。此外，如果对该区域调用cudaMemPrefetchAsync或cudaMemPrefetchAsync_v2，将在目标处理器上创建数据的只读副本。若cudaMemPrefetchAsync_v2的目标位置是主机NUMA节点且另一个主机NUMA节点已存在只读副本，则该副本将被迁移至目标主机NUMA节点。任何处理器写入该区域时，除发生写入的副本外，相应页面的所有其他副本都将失效。若写入处理器是CPU且页面的首选位置是主机NUMA节点，则该页面也将被迁移至该主机NUMA节点。此建议将忽略location参数。请注意，要实现页面读取复制，访问处理器必须是CPU或具有设备属性cudaDevAttrConcurrentManagedAccess非零值的GPU。此外，如果在未设置设备属性cudaDevAttrConcurrentManagedAccess的设备上创建上下文，则在这些上下文全部销毁前不会发生读取复制。若内存区域指向有效的系统分配可分页内存，则访问设备必须具有设备属性cudaDevAttrPageableMemoryAccess非零值才能在该设备上创建只读副本。但需注意，若访问设备同时具有设备属性cudaDevAttrPageableMemoryAccessUsesHostPageTables非零值，则设置此建议不会在该设备访问此内存区域时创建只读副本。

cudaMemAdviceUnsetReadMostly: 撤销cudaMemAdviseSetReadMostly的效果，并阻止统一内存驱动程序尝试对该内存范围进行启发式读取复制。任何读取复制的数据副本都将合并为单个副本。如果页面有首选位置且其中一个读取复制的副本驻留在该位置，则合并后的副本将位于首选位置。否则，所选位置是任意的。注意：此建议将忽略location参数。

cudaMemAdviseSetPreferredLocation: This advice sets the preferred location for the data to be the memory belonging to location. When cudaMemLocation::type is cudaMemLocationTypeHost, cudaMemLocation::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 cudaMemLocation::type to cudaMemLocationTypeHostNuma and cudaMemLocation::id must specify the NUMA ID of the host NUMA node. If cudaMemLocation::type is set to cudaMemLocationTypeHostNumaCurrent, cudaMemLocation::id will be ignored and the host NUMA node closest to the calling thread's CPU will be used as the preferred location. If cudaMemLocation::type is a cudaMemLocationTypeDevice, then cudaMemLocation::id must be a valid device ordinal and the device must have a non-zero value for the device attribute cudaDevAttrConcurrentManagedAccess. 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 cudaMemPrefetchAsync. 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 cudaMemAdviseSetReadMostly 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 cudaMemAdviseSetReadMostly. If the memory region refers to valid system-allocated pageable memory, and cudaMemLocation::type is cudaMemLocationTypeDevice then cudaMemLocation::id must be a valid device that has a non-zero alue for the device attribute cudaDevAttrPageableMemoryAccess.

cudaMemAdviseUnsetPreferredLocation: 撤销cudaMemAdviseSetPreferredLocation的效果并将首选位置设置为无。此建议将忽略location参数。

cudaMemAdviseSetAccessedBy: This advice implies that the data will be accessed by processor location. The cudaMemLocation::type must be either cudaMemLocationTypeDevice with cudaMemLocation::id representing a valid device ordinal or cudaMemLocationTypeHost and cudaMemLocation::id will be ignored. All other location types are invalid. If cudaMemLocation::id is a GPU, then the device attribute cudaDevAttrConcurrentManagedAccess 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 cudaMemAdviseSetAccessedBy flag set for this data will now have its mapping updated to point to the page in host memory. If cudaMemAdviseSetReadMostly 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 CU_MEM_ADVISE_SET_PREFERRED_LOCATION will override the policies of this advice. If the memory region refers to valid system-allocated pageable memory, and cudaMemLocation::type is cudaMemLocationTypeDevice then device in cudaMemLocation::id must have a non-zero value for the device attribute cudaDevAttrPageableMemoryAccess. Additionally, if cudaMemLocation::id has a non-zero value for the device attribute cudaDevAttrPageableMemoryAccessUsesHostPageTables, then this call has no effect.

CU_MEM_ADVISE_UNSET_ACCESSED_BY: 撤销cudaMemAdviseSetAccessedBy的效果。来自location的任何数据映射可能随时被移除，导致访问产生非致命页面错误。如果内存区域指向有效的系统分配可分页内存，且cudaMemLocation::type为cudaMemLocationTypeDevice，则cudaMemLocation::id中的设备必须具有设备属性cudaDevAttrPageableMemoryAccess的非零值。此外，如果cudaMemLocation::id对于设备属性cudaDevAttrPageableMemoryAccessUsesHostPageTables具有非零值，则此调用无效。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpy3DPeerAsync, cudaMemPrefetchAsync, cuMemAdvise, cuMemAdvise_v2

__host__ cudaError_t cudaMemGetInfo ( size_t* free, size_t* total )

获取设备的空闲和总内存。

参数

free: - Returned free memory in bytes
total: - Returned total memory in bytes

cudaSuccess, cudaErrorInvalidValue, cudaErrorLaunchFailure

描述

在*total中返回当前上下文可用的内存总量。在*free中返回操作系统报告的设备空闲内存量。CUDA不保证能够分配操作系统报告的所有空闲内存。在多租户场景下，返回的空闲内存估算值容易受到竞态条件影响——即在估算空闲内存与报告之间，其他进程或同一进程中的其他线程执行了新的内存分配/释放操作，将导致报告的空闲值与实际空闲内存存在偏差。

Tegra集成的GPU与CPU及SoC其他组件共享内存。该API返回的空闲和总内存值不包括某些平台上操作系统维护的SWAP交换内存空间。当GPU或CPU分配或访问内存时，操作系统可能会将部分内存页移入交换区。有关如何计算Tegra总内存和空闲内存的方法，请参阅Tegra应用说明。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cuMemGetInfo

__host__ cudaError_t cudaMemPrefetchAsync ( const void* devPtr, size_t count, int dstDevice, cudaStream_t stream = 0 )

将内存预取到指定的目标设备。

参数

devPtr: - Pointer to be prefetched
count: - Size in bytes
dstDevice: - Destination device to prefetch to
stream: - Stream to enqueue prefetch operation

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

将内存预取到指定的目标设备。devPtr是要预取内存的基设备指针，dstDevice是目标设备。count指定要复制的字节数。stream是操作入队的流。内存范围必须引用通过cudaMallocManaged分配的托管内存或通过__managed__变量声明的内存，在具有非零cudaDevAttrPageableMemoryAccess的系统上，它也可以引用系统分配的内存。

为dstDevice传入cudaCpuDeviceId会将数据预取到主机内存。如果dstDevice是GPU，则设备属性cudaDevAttrConcurrentManagedAccess必须非零。此外，stream必须与具有非零值设备属性cudaDevAttrConcurrentManagedAccess的设备相关联。

在将预取操作加入流之前，内存范围的起始地址和结束地址将分别向下舍入和向上舍入，以与CPU页面大小对齐。

如果该内存区域尚未分配物理内存，则该内存区域将在目标设备上填充并映射。如果没有足够的内存预取所需区域，统一内存驱动程序可能会将其他cudaMallocManaged分配的内存页驱逐到主机内存以腾出空间。使用cudaMalloc或cudaMallocArray分配的设备内存不会被驱逐。

默认情况下，迁移页面前一位置的所有映射都会被移除，而新位置的映射仅会在dstDevice设备上建立。但具体行为还取决于通过cudaMemAdvise对此内存范围应用的设置，如下所述：

如果在此内存范围的任何子集上设置了cudaMemAdviseSetReadMostly，则该子集将在dstDevice上创建页面的只读副本。

如果在此内存范围的任何子集上调用了cudaMemAdviseSetPreferredLocation，那么即使dstDevice不是该内存范围内任何页面的首选位置，这些页面也将被迁移到dstDevice。

如果在此内存范围的任何子集上调用了cudaMemAdviseSetAccessedBy，那么来自所有适当处理器的对这些页面的映射将被更新以指向新位置（如果能够建立此类映射）。否则，这些映射将被清除。

请注意，此API并非功能必需，仅用于通过允许应用程序在数据被访问前将其迁移至合适位置来提升性能。对该内存范围的访问始终是连贯的，即使数据正在主动迁移过程中也允许访问。

请注意，此函数相对于主机和其他设备上的所有工作是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpy3DPeerAsync, cudaMemAdvise, cudaMemAdvise_v2 cuMemPrefetchAsync

__host__ cudaError_t cudaMemPrefetchAsync_v2 ( const void* devPtr, size_t count, cudaMemLocation location, unsigned int flags, cudaStream_t stream = 0 )

将内存预取到指定的目标位置。

参数

devPtr: - Pointer to be prefetched
count: - Size in bytes
location: - location to prefetch to
flags: - flags for future use, must be zero now.
stream: - Stream to enqueue prefetch operation

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

将内存预取到指定的目标位置。devPtr是要预取内存的基设备指针，location指定目标位置。count指定要复制的字节数。stream是操作入队的流。内存范围必须引用通过cudaMallocManaged分配的托管内存或通过__managed__变量声明的内存，在具有非零cudaDevAttrPageableMemoryAccess的系统上，它也可以引用系统分配的内存。

为cudaMemLocation::type指定cudaMemLocationTypeDevice会将内存预取到由设备序号cudaMemLocation::id指定的GPU上，该设备必须具有非零值的device属性concurrentManagedAccess。此外，stream必须关联到一个device属性concurrentManagedAccess为非零值的设备。为cudaMemLocation::type指定cudaMemLocationTypeHost会将数据预取到主机内存。应用程序可以通过为cudaMemLocation::type指定cudaMemLocationTypeHostNuma并在cudaMemLocation::id中指定有效的主机NUMA节点ID，来请求将内存预取到特定的主机NUMA节点。用户还可以通过为cudaMemLocation::type指定cudaMemLocationTypeHostNumaCurrent，请求将内存预取到最接近当前线程CPU的主机NUMA节点。请注意，当cudaMemLocation::type是cudaMemLocationTypeHost或cudaMemLocationTypeHostNumaCurrent时，cudaMemLocation::id将被忽略。

在将预取操作加入流之前，内存范围的起始地址和结束地址将分别向下舍入和向上舍入，以与CPU页面大小对齐。

默认情况下，迁移页面前一位置的所有映射都会被移除，且新位置的映射仅会在目标位置建立。但具体行为还取决于通过cuMemAdvise对此内存范围应用的设置，如下所述：

如果在此内存范围的任何子集上设置了cudaMemAdviseSetReadMostly，则该子集将在目标位置创建页面的只读副本。但如果目标位置是主机NUMA节点，则该子集中已位于其他主机NUMA节点的任何页面都将被传输到目标位置。

如果在此内存范围的任何子集上调用了cudaMemAdviseSetPreferredLocation，那么即使location不是该内存范围中任何页面的首选位置，这些页面也将被迁移到location。

请注意，此API并非功能必需，仅用于通过允许应用程序在数据被访问前将其迁移至合适位置来提升性能。对该内存范围的访问始终保持一致性，即使数据正在主动迁移过程中也允许访问。

请注意，此函数相对于主机和其他设备上的所有工作是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数用例中表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpy3DPeerAsync, cudaMemAdvise, cudaMemAdvise_v2 cuMemPrefetchAsync

__host__ cudaError_t cudaMemRangeGetAttribute ( void* data, size_t dataSize, cudaMemRangeAttribute attribute, const void* devPtr, size_t count )

查询给定内存范围的属性。

参数

data: - A pointers to a memory location where the result of each attribute query will be written to.
dataSize: - Array containing the size of data
attribute: - The attribute to query
devPtr: - Start of the range to query
count: - Size of the range to query

cudaSuccess, cudaErrorInvalidValue

描述

查询从devPtr开始、大小为count字节的内存范围的属性。该内存范围必须指向通过cudaMallocManaged分配的托管内存或通过__managed__变量声明的内存。

attribute 参数可以接受以下值：

cudaMemRangeAttributeReadMostly: 如果指定此属性，data将被解释为32位整数，且dataSize必须为4。如果给定内存范围内的所有页面都启用了读取复制功能，则返回结果为1，否则返回0。
cudaMemRangeAttributePreferredLocation: 如果指定此属性，data将被解释为32位整数，且dataSize必须为4。返回的结果将是GPU设备ID（如果内存范围内所有页面的首选位置都是该GPU），或是cudaCpuDeviceId（如果所有页面的首选位置都是CPU），或是cudaInvalidDeviceId（如果页面不具有相同的首选位置或部分页面根本没有首选位置）。请注意，查询时内存范围内页面的实际位置可能与首选位置不同。
cudaMemRangeAttributeAccessedBy: 如果指定此属性，data将被解释为一个32位整数数组，且dataSize必须是4的非零倍数。返回的结果将是一个设备ID列表，这些设备已为该整个内存范围设置了cudaMemAdviceSetAccessedBy。如果任何设备未对该整个内存范围设置该建议，则该设备将不会被包含。如果data大于已为该内存范围设置该建议的设备数量，则所有额外空间将返回cudaInvalidDeviceId。例如，如果dataSize为12（即data有3个元素）且只有设备0设置了该建议，则返回的结果将是{ 0, cudaInvalidDeviceId, cudaInvalidDeviceId }。如果data小于已设置该建议的设备数量，则只会返回能放入数组的设备数量。然而，不能保证会返回哪些特定设备。
cudaMemRangeAttributeLastPrefetchLocation: 如果指定此属性，data将被解释为32位整数，且dataSize必须为4。返回的结果将是内存范围内所有页面通过cudaMemPrefetchAsync显式预取的最后一个位置。根据预取的最后一个位置是GPU还是CPU，结果将分别是GPU ID或cudaCpuDeviceId。如果内存范围内有任何页面从未显式预取过，或者所有页面未被预取到同一位置，则将返回cudaInvalidDeviceId。请注意，这仅返回应用程序请求将内存范围预取到的最后一个位置。它并不指示预取操作到该位置是否已完成或甚至已开始。
cudaMemRangeAttributePreferredLocationType: If this attribute is specified, data will be interpreted as a cudaMemLocationType, and dataSize must be sizeof(cudaMemLocationType). The cudaMemLocationType returned will be cudaMemLocationTypeDevice if all pages in the memory range have the same GPU as their preferred location, or cudaMemLocationType will be cudaMemLocationTypeHost if all pages in the memory range have the CPU as their preferred location, or or it will be cudaMemLocationTypeHostNuma if all the pages in the memory range have the same host NUMA node ID as their preferred location or it will be cudaMemLocationTypeInvalid 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.
- cudaMemRangeAttributePreferredLocationId: 如果指定此属性，data将被解释为32位整数，且dataSize必须为4。如果对相同地址范围的cudaMemRangeAttributePreferredLocationType查询返回cudaMemLocationTypeDevice，则它将是有效的设备序号；如果返回cudaMemLocationTypeHostNuma，则它将是有效的主机NUMA节点ID；如果返回任何其他位置类型，则应忽略该ID。
cudaMemRangeAttributeLastPrefetchLocationType: If this attribute is specified, data will be interpreted as a cudaMemLocationType, and dataSize must be sizeof(cudaMemLocationType). The result returned will be the last location type to which all pages in the memory range were prefetched explicitly via cuMemPrefetchAsync. The cudaMemLocationType returned will be cudaMemLocationTypeDevice if the last prefetch location was the GPU or cudaMemLocationTypeHost if it was the CPU or cudaMemLocationTypeHostNuma 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, CUmemLocationType will be cudaMemLocationTypeInvalid. 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.
- cudaMemRangeAttributeLastPrefetchLocationId: 如果指定此属性，data将被解释为32位整数，且dataSize必须为4。如果对相同地址范围的cudaMemRangeAttributeLastPrefetchLocationType查询返回cudaMemLocationTypeDevice，则它将是有效的设备序号；如果返回cudaMemLocationTypeHostNuma，则它将是有效的主机NUMA节点ID；如果返回任何其他位置类型，则应忽略该ID。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemRangeGetAttributes, cudaMemPrefetchAsync, cudaMemAdvise, cuMemRangeGetAttribute

__host__ cudaError_t cudaMemRangeGetAttributes ( void** data, size_t* dataSizes, cudaMemRangeAttribute ** attributes, size_t numAttributes, const void* devPtr, size_t count )

查询给定内存范围的属性。

参数

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

cudaSuccess, cudaErrorInvalidValue

描述

查询从devPtr开始、大小为count字节的内存范围的属性。该内存范围必须指向通过cudaMallocManaged分配的托管内存或通过__managed__变量声明的内存。attributes数组将被解释为包含numAttributes个条目。dataSizes数组同样会被解释为包含numAttributes个条目。查询结果将存储在data中。

以下是支持的属性列表。有关属性的描述和限制，请参阅cudaMemRangeGetAttribute。

cudaMemRangeAttributeReadMostly
cudaMemRangeAttributePreferredLocation
cudaMemRangeAttributeAccessedBy
cudaMemRangeAttributeLastPrefetchLocation
:: cudaMemRangeAttributePreferredLocationType
:: cudaMemRangeAttributePreferredLocationId
:: cudaMemRangeAttributeLastPrefetchLocationType
:: cudaMemRangeAttributeLastPrefetchLocationId

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemRangeGetAttribute, cudaMemAdvise, cudaMemPrefetchAsync, cuMemRangeGetAttributes

__host__ cudaError_t cudaMemcpy ( void* dst, const void* src, size_t count, cudaMemcpyKind kind )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
src: - Source memory address
count: - Size in bytes to copy
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidMemcpyDirection

描述

将count字节从src指向的内存区域复制到dst指向的内存区域，其中kind指定了复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型将从指针值推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上允许使用。使用与复制方向不匹配的dst和src指针调用cudaMemcpy()会导致未定义行为。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
该函数在大多数使用场景下表现出同步行为。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未在CUDA中注册的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpyDtoH, cuMemcpyHtoD, cuMemcpyDtoD, cuMemcpy

__host__ cudaError_t cudaMemcpy2D ( void* dst, size_t dpitch, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
dpitch: - Pitch of destination memory
src: - Source memory address
spitch: - Pitch of source memory
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

将一个矩阵（包含height行，每行width字节）从src指向的内存区域复制到dst指向的内存区域，其中kind指定了复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。dpitch和spitch分别表示dst和src指向的二维数组在内存中的宽度（以字节为单位），包括每行末尾可能添加的填充。内存区域不得重叠。width不得超过dpitch或spitch。如果调用cudaMemcpy2D()时dst和src指针与复制方向不匹配，将导致未定义行为。如果dpitch或spitch超过允许的最大值，cudaMemcpy2D()将返回错误。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未注册CUDA的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2D, cuMemcpy2DUnaligned

__host__ cudaError_t cudaMemcpy2DArrayToArray ( cudaArray_t dst, size_t wOffsetDst, size_t hOffsetDst, cudaArray_const_t src, size_t wOffsetSrc, size_t hOffsetSrc, size_t width, size_t height, cudaMemcpyKind kind = cudaMemcpyDeviceToDevice )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
wOffsetDst: - Destination starting X offset (columns in bytes)
hOffsetDst: - Destination starting Y offset (rows)
src: - Source memory address
wOffsetSrc: - Source starting X offset (columns in bytes)
hOffsetSrc: - Source starting Y offset (rows)
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidMemcpyDirection

描述

将一个矩阵（包含height行，每行width字节）从CUDA数组src的左上角偏移hOffsetSrc行和wOffsetSrc字节处复制到CUDA数组dst的左上角偏移hOffsetDst行和wOffsetDst字节处，其中kind指定了复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。wOffsetDst + width不得超过CUDA数组dst的宽度。wOffsetSrc + width不得超过CUDA数组src的宽度。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2D, cuMemcpy2DUnaligned

__host__ __device__ cudaError_t cudaMemcpy2DAsync ( void* dst, size_t dpitch, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
dpitch: - Pitch of destination memory
src: - Source memory address
spitch: - Pitch of source memory
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

将一个矩阵（包含height行，每行width字节）从src指向的内存区域复制到dst指向的内存区域，其中kind参数指定复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅支持在具备统一虚拟寻址功能的系统中使用。dpitch和spitch分别表示dst和src指向的二维数组在内存中的字节宽度（包含每行末尾可能存在的填充字节）。内存区域不得重叠，且width不得超过dpitch或spitch的值。

调用cudaMemcpy2DAsync()时，如果dst和src指针与复制方向不匹配，会导致未定义行为。如果dpitch或spitch超过允许的最大值，cudaMemcpy2DAsync()将返回错误。

cudaMemcpy2DAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到流。如果kind是cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost且stream非零，复制操作可能与其他流中的操作重叠。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未在CUDA中注册的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2DAsync

__host__ cudaError_t cudaMemcpy2DFromArray ( void* dst, size_t dpitch, cudaArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, cudaMemcpyKind kind )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
dpitch: - Pitch of destination memory
src: - Source memory address
wOffset: - Source starting X offset (columns in bytes)
hOffset: - Source starting Y offset (rows)
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

从CUDA数组src的左上角偏移hOffset行和wOffset字节处开始，复制一个矩阵（height行，每行width字节）到dst指向的内存区域，其中kind指定复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。dpitch是dst指向的2D数组在内存中的宽度（以字节为单位），包括每行末尾可能添加的填充。wOffset + width不得超过CUDA数组src的宽度。width不得超过dpitch。如果dpitch超过允许的最大值，cudaMemcpy2DFromArray()将返回错误。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须完全在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未在CUDA中注册的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2D, cuMemcpy2DUnaligned

__host__ cudaError_t cudaMemcpy2DFromArrayAsync ( void* dst, size_t dpitch, cudaArray_const_t src, size_t wOffset, size_t hOffset, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
dpitch: - Pitch of destination memory
src: - Source memory address
wOffset: - Source starting X offset (columns in bytes)
hOffset: - Source starting Y offset (rows)
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

从CUDA数组src的左上角偏移hOffset行和wOffset字节处开始，复制一个矩阵（包含height行，每行width字节）到dst指向的内存区域。kind参数指定复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。dpitch表示dst指向的二维数组在内存中的字节宽度（包含每行末尾的填充）。wOffset + width不得超过CUDA数组src的宽度。width不得超过dpitch。如果dpitch超过允许的最大值，cudaMemcpy2DFromArrayAsync()将返回错误。

cudaMemcpy2DFromArrayAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到流。如果kind是cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost且stream非零，复制操作可能与其他流中的操作重叠。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未注册CUDA的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync,

cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2DAsync

__host__ cudaError_t cudaMemcpy2DToArray ( cudaArray_t dst, size_t wOffset, size_t hOffset, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
wOffset: - Destination starting X offset (columns in bytes)
hOffset: - Destination starting Y offset (rows)
src: - Source memory address
spitch: - Pitch of source memory
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

将一个矩阵（包含height行，每行width字节）从src指向的内存区域复制到CUDA数组dst中，起始位置为左上角偏移hOffset行和wOffset字节处。kind参数指定复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。spitch表示src指向的二维数组在内存中的字节宽度（包含每行末尾可能添加的填充字节）。wOffset + width不得超过CUDA数组dst的宽度。width不得超过spitch。如果spitch超过允许的最大值，cudaMemcpy2DToArray()将返回错误。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未在CUDA中注册的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2D, cuMemcpy2DUnaligned

__host__ cudaError_t cudaMemcpy2DToArrayAsync ( cudaArray_t dst, size_t wOffset, size_t hOffset, const void* src, size_t spitch, size_t width, size_t height, cudaMemcpyKind kind, cudaStream_t stream = 0 )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
wOffset: - Destination starting X offset (columns in bytes)
hOffset: - Destination starting Y offset (rows)
src: - Source memory address
spitch: - Pitch of source memory
width: - Width of matrix transfer (columns in bytes)
height: - Height of matrix transfer (rows)
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

将一个矩阵（包含height行，每行width字节）从src指向的内存区域复制到CUDA数组dst中，起始位置为左上角偏移hOffset行和wOffset字节处。kind参数指定复制方向，必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。spitch表示src指向的二维数组在内存中的字节宽度（包含每行末尾可能添加的填充）。wOffset + width不得超过CUDA数组dst的宽度。width不得超过spitch。如果spitch超过允许的最大值，cudaMemcpy2DToArrayAsync()将返回错误。

cudaMemcpy2DToArrayAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到某个流。如果kind是cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost且stream非零，复制操作可能与其他流中的操作重叠。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数用例中表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未注册CUDA的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync,

cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy2DAsync

__host__ cudaError_t cudaMemcpy3D ( const cudaMemcpy3DParms* p )

在3D对象之间复制数据。

参数

p: - 3D memory copy parameters

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

‎struct cudaExtent {
        size_t width;
        size_t height;
        size_t depth;
      };
      struct cudaExtent 
                  make_cudaExtent(size_t w, size_t h, size_t d);
      
      struct cudaPos {
        size_t x;
        size_t y;
        size_t z;
      };
      struct cudaPos 
                  make_cudaPos(size_t x, size_t y, size_t z);
      
      struct cudaMemcpy3DParms {
        cudaArray_t           
                  srcArray;
        struct cudaPos        
                  srcPos;
        struct cudaPitchedPtr 
                  srcPtr;
        cudaArray_t           
                  dstArray;
        struct cudaPos        
                  dstPos;
        struct cudaPitchedPtr 
                  dstPtr;
        struct cudaExtent     
                  extent;
        enum cudaMemcpyKind   
                  kind;
      };

cudaMemcpy3D() 用于在两个3D对象之间复制数据。源对象和目标对象可以位于主机内存、设备内存或CUDA数组中。复制操作的源、目标、范围及类型由cudaMemcpy3DParms结构体指定，该结构体在使用前应初始化为零：

‎cudaMemcpy3DParms myParms = {0};

传递给cudaMemcpy3D()的结构体必须指定srcArray或srcPtr中的一个，以及dstArray或dstPtr中的一个。传递多个非零的源或目标将导致cudaMemcpy3D()返回错误。

srcPos 和 dstPos 字段是源对象和目标对象中的可选偏移量，以每个对象的元素为单位定义。主机或设备指针的元素假定为 unsigned char。

extent字段定义了传输区域的维度（以元素为单位）。如果复制操作涉及CUDA数组，则范围以该数组的元素定义。如果复制操作不涉及CUDA数组，则范围以unsigned char类型的元素定义。

kind字段定义了拷贝的方向。它必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，在这种情况下传输类型将从指针值推断。然而，cudaMemcpyDefault仅在支持统一虚拟寻址的系统上允许。对于传递为kind的cudaMemcpyHostToHost或cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost以及传递为源或目标的cudaArray类型，如果kind暗示cudaArray类型存在于主机上，cudaMemcpy3D()将忽略该暗示，并根据cudaArray类型只能存在于设备上的事实静默修正kind值。

如果源和目标都是数组，当它们的元素大小不一致时，cudaMemcpy3D()将返回错误。

源对象和目标对象不能重叠。如果指定的源对象和目标对象存在重叠，将导致未定义的行为。

源对象必须完全包含由srcPos和extent定义的区域。目标对象必须完全包含由dstPos和extent定义的区域。

cudaMemcpy3D() 如果srcPtr或dstPtr的间距超过允许的最大值，将返回错误。使用cudaMalloc3D()分配的cudaPitchedPtr的间距始终有效。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc3D, cudaMalloc3DArray, cudaMemset3D, cudaMemcpy3DAsync, cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, make_cudaExtent, make_cudaPos, cuMemcpy3D

__host__ __device__ cudaError_t cudaMemcpy3DAsync ( const cudaMemcpy3DParms* p, cudaStream_t stream = 0 )

在3D对象之间复制数据。

参数

p: - 3D memory copy parameters
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidPitchValue, cudaErrorInvalidMemcpyDirection

描述

‎struct cudaExtent {
        size_t width;
        size_t height;
        size_t depth;
      };
      struct cudaExtent 
                  make_cudaExtent(size_t w, size_t h, size_t d);
      
      struct cudaPos {
        size_t x;
        size_t y;
        size_t z;
      };
      struct cudaPos 
                  make_cudaPos(size_t x, size_t y, size_t z);
      
      struct cudaMemcpy3DParms {
        cudaArray_t           
                  srcArray;
        struct cudaPos        
                  srcPos;
        struct cudaPitchedPtr 
                  srcPtr;
        cudaArray_t           
                  dstArray;
        struct cudaPos        
                  dstPos;
        struct cudaPitchedPtr 
                  dstPtr;
        struct cudaExtent     
                  extent;
        enum cudaMemcpyKind   
                  kind;
      };

cudaMemcpy3DAsync() 在两个3D对象之间复制数据。源对象和目标对象可以位于主机内存、设备内存或CUDA数组中。通过cudaMemcpy3DParms结构体指定源、目标、范围以及执行的复制类型，该结构体在使用前应初始化为零：

‎cudaMemcpy3DParms myParms = {0};

传递给cudaMemcpy3DAsync()的结构体必须指定srcArray或srcPtr中的一个，以及dstArray或dstPtr中的一个。传递多个非零源或目标将导致cudaMemcpy3DAsync()返回错误。

srcPos 和 dstPos 字段是源对象和目标对象中的可选偏移量，以每个对象的元素为单位定义。对于主机或设备指针，元素假定为 unsigned char 类型。对于 CUDA 数组，任何维度的位置必须在 [0, 2048) 范围内。

extent字段定义了以元素为单位的传输区域维度。如果CUDA数组参与复制操作，则范围以该数组的元素为单位定义。如果没有CUDA数组参与复制，则范围以unsigned char类型的元素为单位定义。

kind字段定义了拷贝的方向。它必须是cudaMemcpyHostToHost、cudaMemcpyHostToDevice、cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault之一。建议传递cudaMemcpyDefault，在这种情况下传输类型将从指针值推断。然而，cudaMemcpyDefault仅在支持统一虚拟寻址的系统上允许。对于作为kind传递的cudaMemcpyHostToHost或cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost以及作为源或目标传递的cudaArray类型，如果kind暗示cudaArray类型存在于主机上，cudaMemcpy3DAsync()将忽略该暗示，并根据cudaArray类型只能存在于设备上的事实静默修正kind。

如果源和目标都是数组，当它们的元素大小不一致时，cudaMemcpy3DAsync()将返回错误。

源对象和目标对象不能重叠。如果指定的源对象和目标对象存在重叠，将导致未定义的行为。

源对象必须完全位于由srcPos和extent定义的区域内。目标对象必须完全位于由dstPos和extent定义的区域内。

cudaMemcpy3DAsync() 如果srcPtr或dstPtr的间距超过允许的最大值，将返回错误。使用cudaMalloc3D()分配的cudaPitchedPtr的间距始终是有效的。

cudaMemcpy3DAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到某个流。如果kind是cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost且stream非零，复制操作可能与其他流中的操作重叠。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMalloc3D, cudaMalloc3DArray, cudaMemset3D, cudaMemcpy3D, cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, :cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, make_cudaExtent, make_cudaPos, cuMemcpy3DAsync

__host__ cudaError_t cudaMemcpy3DBatchAsync ( size_t numOps, cudaMemcpy3DBatchOp* opList, size_t* failIdx, unsigned long long flags, cudaStream_t stream )

异步执行一批3D内存拷贝操作。

参数

numOps: - Total number of memcpy operations.
opList: - Array of size numOps containing the actual memcpy operations.
failIdx: - 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: - Flags for future use, must be zero now.
stream

cudaSuccess cudaErrorInvalidValue

描述

执行一批内存复制操作。整个批次按流顺序执行，但不保证批次内的复制操作按任何特定顺序执行。请注意，这意味着在批次内指定任何依赖的复制操作将导致未定义行为。

按照opList数组中指定的内容执行内存拷贝操作。该数组的长度由numOps指定。数组中的每个条目描述一个拷贝操作，其中包括拷贝的源操作数和目标操作数，分别由cudaMemcpy3DBatchOp::src和cudaMemcpy3DBatchOp::dst指定。拷贝的源操作数和目标操作数可以是指针或CUDA数组。拷贝的宽度、高度和深度由cudaMemcpy3DBatchOp::extent指定，这些维度值以元素为单位且不能为零。对于指针到指针的拷贝，元素大小被视为1。对于指针到CUDA数组或反之的拷贝，元素大小由CUDA数组决定。对于CUDA数组到CUDA数组的拷贝，两个CUDA数组的元素大小必须匹配。

对于给定的操作数，如果cudaMemcpy3DOperand::type被指定为cudaMemcpyOperandTypePointer，则将使用cudaMemcpy3DOperand::op::ptr。cudaMemcpy3DOperand::op::ptr::ptr字段必须包含复制起始位置的指针。cudaMemcpy3DOperand::op::ptr::rowLength字段指定每行的元素长度，必须为零或大于等于cudaMemcpy3DBatchOp::extent::width中指定的复制宽度。cudaMemcpy3DOperand::op::ptr::layerHeight字段指定每层的高度，必须为零或大于等于cudaMemcpy3DBatchOp::extent::height中指定的复制高度。当这些值为零时，操作数的对应维度将被视为根据复制范围紧密打包。对于cudaDevAttrConcurrentManagedAccess为true的设备上的托管内存指针，或cudaDevAttrPageableMemoryAccess为true的设备上系统分配的可分页内存，cudaMemcpy3DOperand::op::ptr::locHint字段可用于提示操作数的位置。

如果操作数类型指定为cudaMemcpyOperandTypeArray，则将使用cudaMemcpy3DOperand::op::array。cudaMemcpy3DOperand::op::array::array字段指定CUDA数组，而cudaMemcpy3DOperand::op::array::offset指定复制操作从该数组的3D偏移位置开始。

cudaMemcpyAttributes::srcAccessOrder 属性指示了与该属性关联的复制操作应遵循的源访问顺序。若将源访问顺序设置为cudaMemcpySrcAccessOrderStream，则源数据将按照流顺序被访问。若设置为cudaMemcpySrcAccessOrderDuringApiCall，则表示对源指针的访问可能不遵循流顺序，但所有访问必须在API调用返回前完成。此标志适用于临时性源数据（例如栈变量），当已知流中无前置操作会访问该内存，且内存生命周期仅限于源变量声明的作用域时。指定此标志允许驱动程序优化复制操作，并免去用户在API调用后同步流的必要。若将源访问顺序设置为cudaMemcpySrcAccessOrderAny，则表示对源指针的访问可能不遵循流顺序，且访问操作甚至可能在API调用返回后发生。此标志适用于在CUDA外部分配的主机指针（例如通过malloc），当已知流中无前置操作会访问该内存时。指定此标志允许驱动程序在特定平台上优化复制操作。opList中的每个内存复制操作必须具有有效的srcAccessOrder设置，否则此API将返回cudaErrorInvalidValue。

cudaMemcpyAttributes::flags 字段可用于指定拷贝操作的特殊标志。设置 cudaMemcpyFlagPreferOverlapWithCompute 标志表示关联的拷贝操作应优先与任何计算工作重叠。请注意，此标志仅作为提示，可能会根据平台和拷贝的其他参数被忽略。

如果在解析批次时遇到任何错误，将返回批次中遇到错误的索引位置，存储在failIdx中。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
请求的内存区域必须完全在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未在CUDA中注册的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

__host__ cudaError_t cudaMemcpy3DPeer ( const cudaMemcpy3DPeerParms* p )

在设备之间复制内存。

参数

p: - Parameters for the memory copy

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice, cudaErrorInvalidPitchValue

描述

根据p中指定的参数执行3D内存复制。有关其参数的文档，请参阅cudaMemcpy3DPeerParms结构的定义。

请注意，只有当传输的源或目标是主机内存时，此函数相对于主机才是同步的。还需注意，此复制操作会与当前设备、复制源设备以及复制目标设备上所有待处理和未来的异步工作序列化（使用cudaMemcpy3DPeerAsync可避免此同步问题）。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpyPeerAsync, cudaMemcpy3DPeerAsync, cuMemcpy3DPeer

__host__ cudaError_t cudaMemcpy3DPeerAsync ( const cudaMemcpy3DPeerParms* p, cudaStream_t stream = 0 )

在设备之间异步复制内存。

参数

p: - Parameters for the memory copy
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice, cudaErrorInvalidPitchValue

描述

根据p中指定的参数执行3D内存复制。有关其参数的文档，请参阅cudaMemcpy3DPeerParms结构的定义。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpyPeerAsync, cudaMemcpy3DPeerAsync, cuMemcpy3DPeerAsync

__host__ __device__ cudaError_t cudaMemcpyAsync ( void* dst, const void* src, size_t count, cudaMemcpyKind kind, cudaStream_t stream = 0 )

在主机和设备之间复制数据。

参数

dst: - Destination memory address
src: - Source memory address
count: - Size in bytes to copy
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidMemcpyDirection

描述

内存区域可能不重叠。使用与复制方向不匹配的dst和src指针调用cudaMemcpyAsync()会导致未定义行为。

cudaMemcpyAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到某个流。如果kind是cudaMemcpyHostToDevice或cudaMemcpyDeviceToHost且stream非零，复制操作可能与其他流中的操作重叠。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未注册CUDA的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpyAsync, cuMemcpyDtoHAsync, cuMemcpyHtoDAsync, cuMemcpyDtoDAsync

__host__ cudaError_t cudaMemcpyBatchAsync ( void** dsts, void** srcs, size_t* sizes, size_t count, cudaMemcpyAttributes* attrs, size_t* attrsIdxs, size_t numAttrs, size_t* failIdx, cudaStream_t stream )

异步执行一批内存拷贝操作。

参数

dsts: - Array of destination pointers.
srcs: - Array of memcpy source pointers.
sizes: - Array of sizes for memcpy operations.
count: - Size of dsts, srcs and sizes arrays
attrs: - Array of memcpy attributes.
attrsIdxs: - 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 of attrs and attrsIdxs arrays.
failIdx: - 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.
stream

cudaSuccess cudaErrorInvalidValue

描述

执行一批内存拷贝操作。这批操作整体上按照流顺序执行，但不保证批次内的拷贝按任何特定顺序执行。此API仅支持指针到指针的拷贝。如需涉及CUDA数组的拷贝，请参阅cudaMemcpy3DBatchAsync。

执行从srcs中指定的源缓冲区到dsts中指定的目标缓冲区的内存拷贝。每次拷贝的大小由sizes指定。这三个数组的长度必须与count指定的值相同。由于批处理中的拷贝操作没有顺序保证，如果在同一批处理中指定了任何有依赖关系的拷贝操作，将会导致未定义行为。

批次中的每个副本都必须与attrs数组中指定的一组属性相关联。该数组中的每个条目可以应用于多个副本。这可以通过在attrsIdxs数组中指定attrs数组对应条目所适用的第一个副本的索引来实现。attrs和attrsIdxs的长度必须与numAttrs指定的相同。例如，如果一个批次在dst/src/sizes中有10个副本，其中前6个具有一组属性，其余4个具有另一组属性，那么numAttrs将为2，attrsIdxs将为{0, 6}，而attrs将包含这两组属性。请注意，attrsIdxs的第一个条目必须始终为0。此外，每个条目必须大于前一个条目，最后一个条目应小于count。此外，numAttrs必须小于或等于count。

cudaMemcpyAttributes::srcAccessOrder 属性指示了与该属性关联的复制操作应遵循的源访问顺序。若将源访问顺序设为cudaMemcpySrcAccessOrderStream，则源数据将按流顺序访问。若设为cudaMemcpySrcAccessOrderDuringApiCall，则表示对源指针的访问可能不遵循流顺序，但所有访问必须在API调用返回前完成。此标志适用于临时性源数据（如栈变量），且已知流中无前置操作会访问该内存，同时内存生命周期仅限于源变量的声明作用域。指定此标志可让驱动程序优化复制操作，并免除用户在API调用后同步流的必要。若设为cudaMemcpySrcAccessOrderAny，则表示对源指针的访问可不遵循流顺序，且访问可能在API调用返回后发生。此标志适用于CUDA外部分配的主机指针（如通过malloc），且已知流中无前置操作会访问该内存。指定此标志可让驱动程序在特定平台上优化复制操作。批次中的每个memcpy操作都必须有对应的有效cudaMemcpyAttributes，包含正确的srcAccessOrder设置，否则API将返回cudaErrorInvalidValue。

cudaMemcpyAttributes::srcLocHint 和 cudaMemcpyAttributes::dstLocHint 允许应用程序为复制操作的操作数指定提示位置，当操作数没有固定位置时。也就是说，这些提示仅适用于在cudaDevAttrConcurrentManagedAccess为true的设备上的托管内存指针，或cudaDevAttrPageableMemoryAccess为true的设备上系统分配的可分页内存。对于其他情况，这些提示将被忽略。

cudaMemcpyAttributes::flags字段可用于指定拷贝操作的特定标志。设置cudaMemcpyFlagPreferOverlapWithCompute标志表示关联的拷贝操作应优先与任何计算工作重叠。请注意，此标志仅作为提示，可能会根据平台和拷贝的其他参数而被忽略。

如果在解析批次时遇到任何错误，将返回批次中遇到错误的索引位置，存储在failIdx中。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
请求的内存区域必须全部在CUDA中注册，或者在主机可分页传输的情况下完全不注册。不支持跨越已注册和未注册CUDA的内存分配区域，此类操作将返回CUDA_ERROR_INVALID_VALUE错误。

__host__ cudaError_t cudaMemcpyFromSymbol ( void* dst, const void* symbol, size_t count, size_t offset = 0, cudaMemcpyKind kind = cudaMemcpyDeviceToHost )

从设备上的给定符号复制数据。

参数

dst: - Destination memory address
symbol: - Device symbol address
count: - Size in bytes to copy
offset: - Offset from start of symbol in bytes
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidSymbol, cudaErrorInvalidMemcpyDirection, cudaErrorNoKernelImageForDevice

描述

从符号symbol起始位置偏移offset字节所指向的内存区域，复制count字节到dst指向的内存区域。内存区域不可重叠。symbol是位于全局或常量内存空间的变量。kind可以是cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy, cuMemcpyDtoH, cuMemcpyDtoD

__host__ cudaError_t cudaMemcpyFromSymbolAsync ( void* dst, const void* symbol, size_t count, size_t offset, cudaMemcpyKind kind, cudaStream_t stream = 0 )

从设备上的给定符号复制数据。

参数

dst: - Destination memory address
symbol: - Device symbol address
count: - Size in bytes to copy
offset: - Offset from start of symbol in bytes
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidSymbol, cudaErrorInvalidMemcpyDirection, cudaErrorNoKernelImageForDevice

描述

从符号symbol起始位置偏移offset字节开始的内存区域，复制count字节到dst指向的内存区域。内存区域不可重叠。symbol是位于全局或常量内存空间的变量。kind可以是cudaMemcpyDeviceToHost、cudaMemcpyDeviceToDevice或cudaMemcpyDefault。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。

cudaMemcpyFromSymbolAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到某个流。如果kind是cudaMemcpyDeviceToHost且stream非零，则复制操作可能与其他流中的操作重叠。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cuMemcpyAsync, cuMemcpyDtoHAsync, cuMemcpyDtoDAsync

__host__ cudaError_t cudaMemcpyPeer ( void* dst, int dstDevice, const void* src, int srcDevice, size_t count )

在两个设备之间复制内存。

参数

dst: - Destination device pointer
dstDevice: - Destination device
src: - Source device pointer
srcDevice: - Source device
count: - Size of memory copy in bytes

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

将内存从一个设备复制到另一个设备的内存。dst是目标内存的基础设备指针，dstDevice是目标设备。src是源内存的基础设备指针，srcDevice是源设备。count指定要复制的字节数。

请注意，此函数相对于主机是异步的，但对于当前设备srcDevice和dstDevice中所有待处理和未来的异步工作则是串行化的（使用cudaMemcpyPeerAsync可避免此同步）。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyAsync, cudaMemcpyPeerAsync, cudaMemcpy3DPeerAsync, cuMemcpyPeer

__host__ cudaError_t cudaMemcpyPeerAsync ( void* dst, int dstDevice, const void* src, int srcDevice, size_t count, cudaStream_t stream = 0 )

在两个设备之间异步复制内存。

参数

dst: - Destination device pointer
dstDevice: - Destination device
src: - Source device pointer
srcDevice: - Source device
count: - Size of memory copy in bytes
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidDevice

描述

请注意，此函数相对于主机和其他设备上的所有工作是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpyPeer, cudaMemcpyAsync, cudaMemcpy3DPeerAsync, cuMemcpyPeerAsync

__host__ cudaError_t cudaMemcpyToSymbol ( const void* symbol, const void* src, size_t count, size_t offset = 0, cudaMemcpyKind kind = cudaMemcpyHostToDevice )

将数据复制到设备上的指定符号。

参数

symbol: - Device symbol address
src: - Source memory address
count: - Size in bytes to copy
offset: - Offset from start of symbol in bytes
kind: - Type of transfer

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidSymbol, cudaErrorInvalidMemcpyDirection, cudaErrorNoKernelImageForDevice

描述

将count字节从src指向的内存区域复制到符号symbol起始位置偏移offset字节处的内存区域。内存区域不得重叠。symbol是位于全局或常量内存空间中的变量。kind可以是cudaMemcpyHostToDevice、cudaMemcpyDeviceToDevice或cudaMemcpyDefault。建议传递cudaMemcpyDefault，此时传输类型将从指针值推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上允许使用。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出同步行为。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyToSymbolAsync, cudaMemcpyFromSymbolAsync, cuMemcpy, cuMemcpyHtoD, cuMemcpyDtoD

__host__ cudaError_t cudaMemcpyToSymbolAsync ( const void* symbol, const void* src, size_t count, size_t offset, cudaMemcpyKind kind, cudaStream_t stream = 0 )

将数据复制到设备上的指定符号。

参数

symbol: - Device symbol address
src: - Source memory address
count: - Size in bytes to copy
offset: - Offset from start of symbol in bytes
kind: - Type of transfer
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidSymbol, cudaErrorInvalidMemcpyDirection, cudaErrorNoKernelImageForDevice

描述

将count字节从src指向的内存区域复制到符号symbol起始位置偏移offset字节处的内存区域。内存区域不得重叠。symbol是位于全局或常量内存空间的变量。kind可以是cudaMemcpyHostToDevice、cudaMemcpyDeviceToDevice或cudaMemcpyDefault。建议传递cudaMemcpyDefault，此时传输类型会根据指针值自动推断。但cudaMemcpyDefault仅在支持统一虚拟寻址的系统上可用。

cudaMemcpyToSymbolAsync() 相对于主机是异步的，因此调用可能在复制完成前就返回。可以通过传递非零的stream参数选择性地将复制操作关联到某个流。如果kind是cudaMemcpyHostToDevice且stream为非零，该复制操作可能与其他流中的操作重叠。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
该函数在大多数使用场景下表现出异步行为。
此函数使用标准的默认流语义。
在CUDA 4.1中已弃用将变量名称字符串作为symbol参数的做法，并在CUDA 5.0中移除了该功能。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemcpy, cudaMemcpy2D, cudaMemcpy2DToArray, cudaMemcpy2DFromArray, cudaMemcpy2DArrayToArray, cudaMemcpyToSymbol, cudaMemcpyFromSymbol, cudaMemcpyAsync, cudaMemcpy2DAsync, cudaMemcpy2DToArrayAsync, cudaMemcpy2DFromArrayAsync, cudaMemcpyFromSymbolAsync, cuMemcpyAsync, cuMemcpyHtoDAsync, cuMemcpyDtoDAsync

__host__ cudaError_t cudaMemset ( void* devPtr, int value, size_t count )

初始化或设置设备内存为一个值。

参数

devPtr: - Pointer to device memory
value: - Value to set for each byte of specified memory
count: - Size in bytes to set

cudaSuccess, cudaErrorInvalidValue,

描述

用常量字节值value填充由devPtr指向的内存区域的前count个字节。

请注意，除非devPtr指向固定的主机内存，否则此函数相对于主机是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步详情。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cuMemsetD8, cuMemsetD16, cuMemsetD32

__host__ cudaError_t cudaMemset2D ( void* devPtr, size_t pitch, int value, size_t width, size_t height )

初始化或将设备内存设置为某个值。

参数

devPtr: - Pointer to 2D device memory
pitch: - Pitch in bytes of 2D device memory(Unused if height is 1)
value: - Value to set for each byte of specified memory
width: - Width of matrix set (columns in bytes)
height: - Height of matrix set (rows)

cudaSuccess, cudaErrorInvalidValue,

描述

将指向dstPtr的矩阵（每行width字节，共height行）设置为指定值value。pitch是指向dstPtr的2D数组的字节宽度，包括每行末尾添加的任何填充。当pitch是由cudaMallocPitch()返回的值时，此函数执行速度最快。

请注意，除非devPtr指向固定的主机内存，否则此函数相对于主机是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步细节。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemset, cudaMemset3D, cudaMemsetAsync, cudaMemset2DAsync, cudaMemset3DAsync, cuMemsetD2D8, cuMemsetD2D16, cuMemsetD2D32

__host__ __device__ cudaError_t cudaMemset2DAsync ( void* devPtr, size_t pitch, int value, size_t width, size_t height, cudaStream_t stream = 0 )

初始化或将设备内存设置为某个值。

参数

devPtr: - Pointer to 2D device memory
pitch: - Pitch in bytes of 2D device memory(Unused if height is 1)
value: - Value to set for each byte of specified memory
width: - Width of matrix set (columns in bytes)
height: - Height of matrix set (rows)
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue,

描述

将指向dstPtr的矩阵（每行width字节，共height行）设置为指定值value。pitch是指向dstPtr的2D数组的字节宽度，包括添加到每行末尾的任何填充。当pitch是由cudaMallocPitch()返回的值时，此函数执行速度最快。

cudaMemset2DAsync() 相对于主机是异步的，因此调用可能在内存设置完成之前就返回。该操作可以选择性地通过传递非零的stream参数与流相关联。如果stream非零，该操作可能与其他流中的操作重叠。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步详情。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemset, cudaMemset2D, cudaMemset3D, cudaMemsetAsync, cudaMemset3DAsync, cuMemsetD2D8Async, cuMemsetD2D16Async, cuMemsetD2D32Async

__host__ cudaError_t cudaMemset3D ( cudaPitchedPtr pitchedDevPtr, int value, cudaExtent extent )

初始化或将设备内存设置为某个值。

参数

pitchedDevPtr: - Pointer to pitched device memory
value: - Value to set for each byte of specified memory
extent: - Size parameters for where to set device memory (width field in bytes)

cudaSuccess, cudaErrorInvalidValue,

描述

将三维数组的每个元素初始化为指定值value。要初始化的对象由pitchedDevPtr定义。pitchedDevPtr的pitch字段表示pitchedDevPtr指向的三维数组在内存中的宽度（以字节为单位），包括添加到每行末尾的任何填充。xsize字段指定每行的逻辑宽度（以字节为单位），而ysize字段指定每个二维切片的高度（以行数为单位）。当height和depth都等于1时，pitchedDevPtr的pitch字段将被忽略。

初始化区域的范围以字节为单位的width（宽度）、行数为单位的height（高度）和切片数为单位的depth（深度）来指定。

当width大于或等于pitchedDevPtr的xsize时，其性能通常会显著优于宽度小于xsize的情况。其次，当height等于pitchedDevPtr的ysize时，其性能也会优于高度小于ysize的情况。

当pitchedDevPtr是通过cudaMalloc3D()分配时，此函数的执行速度最快。

请注意，除非pitchedDevPtr指向固定的主机内存，否则此函数相对于主机是异步的。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步细节。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemset, cudaMemset2D, cudaMemsetAsync, cudaMemset2DAsync, cudaMemset3DAsync, cudaMalloc3D, make_cudaPitchedPtr, make_cudaExtent

__host__ __device__ cudaError_t cudaMemset3DAsync ( cudaPitchedPtr pitchedDevPtr, int value, cudaExtent extent, cudaStream_t stream = 0 )

初始化或将设备内存设置为某个值。

参数

pitchedDevPtr: - Pointer to pitched device memory
value: - Value to set for each byte of specified memory
extent: - Size parameters for where to set device memory (width field in bytes)
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue,

描述

初始化区域的范围以字节为单位的width、行数为单位的height和切片数为单位的depth来指定。

当width大于或等于pitchedDevPtr的xsize时，范围性能通常会显著优于宽度小于xsize的情况。其次，当height等于pitchedDevPtr的ysize时，其性能也会优于高度小于ysize的情况。

当pitchedDevPtr是通过cudaMalloc3D()分配时，此函数的执行速度最快。

cudaMemset3DAsync() 相对于主机是异步的，因此调用可能在内存设置完成之前就返回。该操作可以选择性地通过传递非零的stream参数与流相关联。如果stream非零，该操作可能与其他流中的操作重叠。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步详情。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemset, cudaMemset2D, cudaMemset3D, cudaMemsetAsync, cudaMemset2DAsync, cudaMalloc3D, make_cudaPitchedPtr, make_cudaExtent

__host__ __device__ cudaError_t cudaMemsetAsync ( void* devPtr, int value, size_t count, cudaStream_t stream = 0 )

初始化或将设备内存设置为某个值。

参数

devPtr: - Pointer to device memory
value: - Value to set for each byte of specified memory
count: - Size in bytes to set
stream: - Stream identifier

cudaSuccess, cudaErrorInvalidValue,

描述

用常量字节值value填充由devPtr指向的内存区域的前count个字节。

cudaMemsetAsync() 相对于主机是异步的，因此调用可能在memset操作完成前就返回。该操作可以选择性地通过传入非零的stream参数与特定流关联。如果stream不为零，该操作可能与其他流中的操作重叠执行。

此函数的设备版本仅处理设备到设备的复制，无法使用本地或共享指针。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
另请参阅 memset同步细节。
此函数使用标准的默认流语义。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaMemset, cudaMemset2D, cudaMemset3D, cudaMemset2DAsync, cudaMemset3DAsync, cuMemsetD8Async, cuMemsetD16Async, cuMemsetD32Async

__host__ cudaError_t cudaMipmappedArrayGetMemoryRequirements ( cudaArrayMemoryRequirements* memoryRequirements, cudaMipmappedArray_t mipmap, int device )

返回CUDA mipmapped数组的内存需求。

参数

memoryRequirements: - Pointer to cudaArrayMemoryRequirements
mipmap: - CUDA mipmapped array to get the memory requirements of
device: - Device to get the memory requirements for

cudaSuccess cudaErrorInvalidValue

描述

返回CUDA多级渐远纹理数组在memoryRequirements中的内存需求。如果该CUDA多级渐远纹理数组未使用cudaArrayDeferredMapping标志进行分配，则将返回cudaErrorInvalidValue错误。

cudaArrayMemoryRequirements::size中的返回值表示CUDA mipmapped数组的总大小。cudaArrayMemoryRequirements::alignment中的返回值表示映射CUDA mipmapped数组所需的对齐要求。

另请参阅：

cudaArrayGetMemoryRequirements

__host__ cudaError_t cudaMipmappedArrayGetSparseProperties ( cudaArraySparseProperties* sparseProperties, cudaMipmappedArray_t mipmap )

返回一个稀疏CUDA mipmapped数组的布局属性。

参数

sparseProperties: - Pointer to return cudaArraySparseProperties
mipmap: - The CUDA mipmapped array to get the sparse properties of

cudaSuccess cudaErrorInvalidValue

描述

返回sparseProperties中的稀疏数组布局属性。如果CUDA mipmapped数组未使用cudaArraySparse标志分配，将返回cudaErrorInvalidValue。

对于非分层的CUDA mipmapped数组，cudaArraySparseProperties::miptailSize返回mip尾部区域的大小。mip尾部区域包含所有宽度、高度或深度小于图块尺寸的mip级别。对于分层的CUDA mipmapped数组，如果cudaArraySparseProperties::flags包含cudaArraySparsePropertiesSingleMipTail，则cudaArraySparseProperties::miptailSize指定所有层组合的mip尾部大小。否则，cudaArraySparseProperties::miptailSize指定每层的mip尾部大小。cudaArraySparseProperties::miptailFirstLevel的返回值仅在cudaArraySparseProperties::miptailSize非零时有效。

另请参阅：

cudaArrayGetSparseProperties, cuMemMapArrayAsync

__host__ cudaExtent make_cudaExtent ( size_t w, size_t h, size_t d )

基于输入参数返回一个cudaExtent。

参数

w: - Width in elements when referring to array memory, in bytes when referring to linear memory
h: - Height in elements
d: - Depth in elements

cudaExtent 由 w、h 和 d 指定

描述

基于指定的输入参数w、h和d返回一个cudaExtent。

另请参阅：

make_cudaPitchedPtr, make_cudaPos

__host__ cudaPitchedPtr make_cudaPitchedPtr ( void* d, size_t p, size_t xsz, size_t ysz )

根据输入参数返回一个cudaPitchedPtr。

参数

d: - Pointer to allocated memory
p: - Pitch of allocated memory in bytes
xsz: - Logical width of allocation in elements
ysz: - Logical height of allocation in elements

cudaPitchedPtr 由 d、p、xsz 和 ysz 指定

描述

根据指定的输入参数 d、p、xsz 和 ysz 返回一个 cudaPitchedPtr。

另请参阅：

make_cudaExtent, make_cudaPos

__host__ cudaPos make_cudaPos ( size_t x, size_t y, size_t z )

根据输入参数返回一个cudaPos。

参数

x: - X position
y: - Y position
z: - Z position

cudaPos 由 x、y 和 z 指定

描述

根据指定的输入参数x、y和z返回一个cudaPos。

另请参阅：

make_cudaExtent, make_cudaPitchedPtr