Merge pull request #1093 from aarongreig/aaron/addBoundsCheckingValidation

Add bounds checking for enqueue operations to the validation layer.

Author: aarongreig

include/ur_api.h

@@ -5972,7 +5972,7 @@ urEnqueueEventsWaitWithBarrier(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferRead(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(offset, size)] handle of the buffer object
     bool blockingRead,                        ///< [in] indicates blocking (true), non-blocking (false)
     size_t offset,                            ///< [in] offset in bytes in the buffer object
     size_t size,                              ///< [in] size in bytes of data being read
@@ -6021,7 +6021,7 @@ urEnqueueMemBufferRead(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferWrite(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(offset, size)] handle of the buffer object
     bool blockingWrite,                       ///< [in] indicates blocking (true), non-blocking (false)
     size_t offset,                            ///< [in] offset in bytes in the buffer object
     size_t size,                              ///< [in] size in bytes of data being written
@@ -6080,7 +6080,7 @@ urEnqueueMemBufferWrite(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferReadRect(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(bufferOrigin, region)] handle of the buffer object
     bool blockingRead,                        ///< [in] indicates blocking (true), non-blocking (false)
     ur_rect_offset_t bufferOrigin,            ///< [in] 3D offset in the buffer
     ur_rect_offset_t hostOrigin,              ///< [in] 3D offset in the host region
@@ -6146,7 +6146,7 @@ urEnqueueMemBufferReadRect(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferWriteRect(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(bufferOrigin, region)] handle of the buffer object
     bool blockingWrite,                       ///< [in] indicates blocking (true), non-blocking (false)
     ur_rect_offset_t bufferOrigin,            ///< [in] 3D offset in the buffer
     ur_rect_offset_t hostOrigin,              ///< [in] 3D offset in the host region
@@ -6199,8 +6199,8 @@ urEnqueueMemBufferWriteRect(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferCopy(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBufferSrc,               ///< [in] handle of the src buffer object
-    ur_mem_handle_t hBufferDst,               ///< [in] handle of the dest buffer object
+    ur_mem_handle_t hBufferSrc,               ///< [in][bounds(srcOffset, size)] handle of the src buffer object
+    ur_mem_handle_t hBufferDst,               ///< [in][bounds(dstOffset, size)] handle of the dest buffer object
     size_t srcOffset,                         ///< [in] offset into hBufferSrc to begin copying from
     size_t dstOffset,                         ///< [in] offset info hBufferDst to begin copying into
     size_t size,                              ///< [in] size in bytes of data being copied
@@ -6252,8 +6252,8 @@ urEnqueueMemBufferCopy(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferCopyRect(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBufferSrc,               ///< [in] handle of the source buffer object
-    ur_mem_handle_t hBufferDst,               ///< [in] handle of the dest buffer object
+    ur_mem_handle_t hBufferSrc,               ///< [in][bounds(srcOrigin, region)] handle of the source buffer object
+    ur_mem_handle_t hBufferDst,               ///< [in][bounds(dstOrigin, region)] handle of the dest buffer object
     ur_rect_offset_t srcOrigin,               ///< [in] 3D offset in the source buffer
     ur_rect_offset_t dstOrigin,               ///< [in] 3D offset in the destination buffer
     ur_rect_region_t region,                  ///< [in] source 3D rectangular region descriptor: width, height, depth
@@ -6307,7 +6307,7 @@ urEnqueueMemBufferCopyRect(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferFill(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(offset, size)] handle of the buffer object
     const void *pPattern,                     ///< [in] pointer to the fill pattern
     size_t patternSize,                       ///< [in] size in bytes of the pattern
     size_t offset,                            ///< [in] offset into the buffer
@@ -6357,7 +6357,7 @@ urEnqueueMemBufferFill(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemImageRead(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hImage,                   ///< [in] handle of the image object
+    ur_mem_handle_t hImage,                   ///< [in][bounds(origin, region)] handle of the image object
     bool blockingRead,                        ///< [in] indicates blocking (true), non-blocking (false)
     ur_rect_offset_t origin,                  ///< [in] defines the (x,y,z) offset in pixels in the 1D, 2D, or 3D image
     ur_rect_region_t region,                  ///< [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D
@@ -6410,7 +6410,7 @@ urEnqueueMemImageRead(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemImageWrite(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hImage,                   ///< [in] handle of the image object
+    ur_mem_handle_t hImage,                   ///< [in][bounds(origin, region)] handle of the image object
     bool blockingWrite,                       ///< [in] indicates blocking (true), non-blocking (false)
     ur_rect_offset_t origin,                  ///< [in] defines the (x,y,z) offset in pixels in the 1D, 2D, or 3D image
     ur_rect_region_t region,                  ///< [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D
@@ -6457,8 +6457,8 @@ urEnqueueMemImageWrite(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemImageCopy(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hImageSrc,                ///< [in] handle of the src image object
-    ur_mem_handle_t hImageDst,                ///< [in] handle of the dest image object
+    ur_mem_handle_t hImageSrc,                ///< [in][bounds(srcOrigin, region)] handle of the src image object
+    ur_mem_handle_t hImageDst,                ///< [in][bounds(dstOrigin, region)] handle of the dest image object
     ur_rect_offset_t srcOrigin,               ///< [in] defines the (x,y,z) offset in pixels in the source 1D, 2D, or 3D
                                               ///< image
     ur_rect_offset_t dstOrigin,               ///< [in] defines the (x,y,z) offset in pixels in the destination 1D, 2D,
@@ -6543,7 +6543,7 @@ typedef enum ur_usm_migration_flag_t {
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueMemBufferMap(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    ur_mem_handle_t hBuffer,                  ///< [in] handle of the buffer object
+    ur_mem_handle_t hBuffer,                  ///< [in][bounds(offset, size)] handle of the buffer object
     bool blockingMap,                         ///< [in] indicates blocking (true), non-blocking (false)
     ur_map_flags_t mapFlags,                  ///< [in] flags for read, write, readwrite mapping
     size_t offset,                            ///< [in] offset in bytes of the buffer region being mapped
@@ -6611,7 +6611,7 @@ urEnqueueMemUnmap(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == ptr`
+///         + `NULL == pMem`
 ///         + `NULL == pPattern`
 ///     - ::UR_RESULT_ERROR_INVALID_QUEUE
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT
@@ -6631,7 +6631,7 @@ urEnqueueMemUnmap(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMFill(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    void *ptr,                                ///< [in] pointer to USM memory object
+    void *pMem,                               ///< [in][bounds(0, size)] pointer to USM memory object
     size_t patternSize,                       ///< [in] the size in bytes of the pattern. Must be a power of 2 and less
                                               ///< than or equal to width.
     const void *pPattern,                     ///< [in] pointer with the bytes of the pattern to set.
@@ -6674,8 +6674,8 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMMemcpy(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
     bool blocking,                            ///< [in] blocking or non-blocking copy
-    void *pDst,                               ///< [in] pointer to the destination USM memory object
-    const void *pSrc,                         ///< [in] pointer to the source USM memory object
+    void *pDst,                               ///< [in][bounds(0, size)] pointer to the destination USM memory object
+    const void *pSrc,                         ///< [in][bounds(0, size)] pointer to the source USM memory object
     size_t size,                              ///< [in] size in bytes to be copied
     uint32_t numEventsInWaitList,             ///< [in] size of the event wait list
     const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
@@ -6720,7 +6720,7 @@ urEnqueueUSMMemcpy(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMPrefetch(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue object
-    const void *pMem,                         ///< [in] pointer to the USM memory object
+    const void *pMem,                         ///< [in][bounds(0, size)] pointer to the USM memory object
     size_t size,                              ///< [in] size in bytes to be fetched
     ur_usm_migration_flags_t flags,           ///< [in] USM prefetch flags
     uint32_t numEventsInWaitList,             ///< [in] size of the event wait list
@@ -6762,7 +6762,7 @@ urEnqueueUSMPrefetch(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMAdvise(
     ur_queue_handle_t hQueue,     ///< [in] handle of the queue object
-    const void *pMem,             ///< [in] pointer to the USM memory object
+    const void *pMem,             ///< [in][bounds(0, size)] pointer to the USM memory object
     size_t size,                  ///< [in] size in bytes to be advised
     ur_usm_advice_flags_t advice, ///< [in] USM memory advice
     ur_event_handle_t *phEvent    ///< [out][optional] return an event object that identifies this particular
@@ -6803,7 +6803,7 @@ urEnqueueUSMAdvise(
 UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMFill2D(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue to submit to.
-    void *pMem,                               ///< [in] pointer to memory to be filled.
+    void *pMem,                               ///< [in][bounds(0, pitch * height)] pointer to memory to be filled.
     size_t pitch,                             ///< [in] the total width of the destination memory including padding.
     size_t patternSize,                       ///< [in] the size in bytes of the pattern. Must be a power of 2 and less
                                               ///< than or equal to width.
@@ -6853,9 +6853,10 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urEnqueueUSMMemcpy2D(
     ur_queue_handle_t hQueue,                 ///< [in] handle of the queue to submit to.
     bool blocking,                            ///< [in] indicates if this operation should block the host.
-    void *pDst,                               ///< [in] pointer to memory where data will be copied.
+    void *pDst,                               ///< [in][bounds(0, dstPitch * height)] pointer to memory where data will
+                                              ///< be copied.
     size_t dstPitch,                          ///< [in] the total width of the source memory including padding.
-    const void *pSrc,                         ///< [in] pointer to memory to be copied.
+    const void *pSrc,                         ///< [in][bounds(0, srcPitch * height)] pointer to memory to be copied.
     size_t srcPitch,                          ///< [in] the total width of the source memory including padding.
     size_t width,                             ///< [in] the width in bytes of each row to be copied.
     size_t height,                            ///< [in] the height of columns to be copied.
@@ -9856,7 +9857,7 @@ typedef struct ur_enqueue_mem_unmap_params_t {
 ///     allowing the callback the ability to modify the parameter's value
 typedef struct ur_enqueue_usm_fill_params_t {
     ur_queue_handle_t *phQueue;
-    void **pptr;
+    void **ppMem;
     size_t *ppatternSize;
     const void **ppPattern;
     size_t *psize;

include/ur_print.hpp

@@ -12512,10 +12512,10 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
                           *(params->phQueue));
 
     os << ", ";
-    os << ".ptr = ";
+    os << ".pMem = ";
 
     ur::details::printPtr(os,
-                          *(params->pptr));
+                          *(params->ppMem));
 
     os << ", ";
     os << ".patternSize = ";

scripts/YaML.md

@@ -616,13 +616,18 @@ class ur_name_t(Structure):
       - `out` is used for params that are write-only; if the param is a pointer, then the memory being pointed to is also write-only
       - `in,out` is used for params that are both read and write; typically this is used for pointers to other data structures that contain both read and write params
       - `nocheck` is used to specify that no additional validation checks will be generated.
-    + `desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[release]"`, `"[typename(typeVarName)]"`}
+    + `desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
       - `optional` is used for params that are handles or pointers where it is legal for the value to be `nullptr`
       - `range` is used for params that are array pointers to specify the valid range that the is valid to read
         + `start` and `end` must be an ISO-C standard identifier or literal
         + `start` is inclusive and `end` is exclusive
       - `release` is used for params that are handles or pointers to handles where the function will destroy any backing memory associated with the handle(s)
       - `typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
+      - `bounds` is used for params that are memory objects or USM allocations. It specifies the range within the memory allocation represented by the param that will be accessed by the operation.
+        + `offset` and `size` must be an ISO-C standard identifier or literal
+        + The sum of `offset` and `size` will be compared against the size of the memory allocation represented by the param.
+        + If `offset` and `size` are not both integers they must be of the types `$x_rect_offset` and `$x_rect_region` respectively.
+        + If `bounds` is used the operation must also take a parameter of type `$x_queue_handle_t`
     + `type` must be an ISO-C standard identifier
     + `name` must be a unique ISO-C standard identifier
   - A param may take the following optional scalar field: {`init`, `version`}