C Specification

To record a command to fill a region in SVM with a pattern of a given pattern size, call the function

// Provided by CL_VERSION_2_0 with cl_khr_command_buffer
cl_int clCommandSVMMemFillKHR(
    cl_command_buffer_khr command_buffer,
    cl_command_queue command_queue,
    const cl_command_properties_khr* properties,
    void* svm_ptr,
    const void* pattern,
    size_t pattern_size,
    size_t size,
    cl_uint num_sync_points_in_wait_list,
    const cl_sync_point_khr* sync_point_wait_list,
    cl_sync_point_khr* sync_point,
    cl_mutable_command_khr* mutable_handle);
clCommandSVMMemFillKHR is provided by the cl_khr_command_buffer extension.

Parameters

  • command_buffer refers to a valid command-buffer object.

  • command_queue specifies the command-queue the command will be recorded to.
    If the cl_khr_command_buffer_multi_device extension is not supported, only a single command-queue is supported, and command_queue must be NULL.
    If the cl_khr_command_buffer_multi_device extension is supported and command_queue is NULL, then only one command-queue must have been set on command_buffer creation; otherwise, command_queue must not be NULL.

  • properties specifies a list of properties for the command and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The cl_khr_command_buffer extension does not define any properties, but supported properties may be defined by layered extensions in future.

  • svm_ptr is a pointer to a (if the device supports system SVM) or SVM memory region that will be filled with pattern. It must be aligned to pattern_size bytes. If svm_ptr is allocated using clSVMAlloc, then it must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

  • pattern is a pointer to the data pattern of size pattern_size in bytes. pattern will be used to fill a region in buffer starting at svm_ptr and is size bytes in size. The data pattern must be a scalar or vector integer or floating-point data type supported by OpenCL. For example, if the region pointed to by svm_ptr is to be filled with a pattern of float4 values, then pattern will be a pointer to a cl_float4 value and pattern_size will be sizeof(cl_float4). The maximum value of pattern_size is the size of the largest integer or floating-point vector data type supported by the OpenCL device. The memory associated with pattern can be reused or freed after the function returns.

  • size is the size in bytes of region being filled starting with svm_ptr and must be a multiple of pattern_size.

  • sync_point_wait_list, num_sync_points_in_wait_list specify synchronization-points that need to complete before this particular command can be executed.

    If sync_point_wait_list is NULL, num_sync_points_in_wait_list must be 0. If sync_point_wait_list is not NULL, the list of synchronization-points pointed to by sync_point_wait_list must be valid and num_sync_points_in_wait_list must be greater than 0. The synchronization-points specified in sync_point_wait_list are device-side synchronization-points. The command-buffer associated with synchronization-points in sync_point_wait_list must be the same as command_buffer. The memory associated with sync_point_wait_list can be reused or freed after the function returns.

  • sync_point returns a synchronization-point ID that identifies this particular command. Synchronization-point objects are unique and can be used to identify this command later on. sync_point can be NULL in which case it will not be possible for the application to record a wait for this command to complete. If the sync_point_wait_list and the sync_point arguments are not NULL, the sync_point argument should not refer to an element of the sync_point_wait_list array.

  • mutable_handle returns a handle to the command. This parameter is unused, and must be NULL.

Description

clCommandSVMMemFillKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the errors defined by clEnqueueSVMMemFill except:

CL_INVALID_COMMAND_QUEUE is replaced with:

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is not supported and command_queue is not NULL.

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is supported; and either command_queue is NULL and command_buffer was created with more than one queue, or command_queue is not NULL and not a command-queue listed on command_buffer creation.

CL_INVALID_CONTEXT is replaced with:

  • CL_INVALID_CONTEXT if command_queue is not NULL, and the context associated with command_queue and command_buffer is not the same.

CL_INVALID_EVENT_WAIT_LIST is replaced with:

  • CL_INVALID_SYNC_POINT_WAIT_LIST_KHR if sync_point_wait_list is NULL and num_sync_points_in_wait_list is > 0, or sync_point_wait_list is not NULL and num_sync_points_in_wait_list is 0, or if synchronization-point objects in sync_point_wait_list are not valid synchronization-points.

New errors:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_OPERATION if command_buffer has been finalized.

  • CL_INVALID_VALUE if values specified in properties are not valid.

  • CL_INVALID_VALUE if mutable_handle is not NULL.

See Also

CL_VERSION_2_0, cl_command_buffer_khr, cl_command_properties_khr, cl_command_queue, cl_khr_command_buffer, cl_mutable_command_khr, cl_sync_point_khr, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0