Merge pull request #2601 from RossBrunton/ross/allocdoc

In docs, mark "allocating" functions as such

Author: RossBrunton

include/ur_api.h

@@ -621,12 +621,13 @@ 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)]"`, `"[retain]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
+    + `desc` may include one or more of the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[alloc]"`, `"[retain]"`, `"[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
-      - `retain` is used for params that are handles or pointers to handles where the function will increment the reference counter associated with the handle(s).
+      - `alloc` is used for output params that are handles or pointers to handles where the function will either increase the reference count by one or create a new handle with an initial reference count of one.
+      - `retain` is used for params that are handles or pointers to handles where the function will increment the reference counter associated with the handle(s). The handle will not be created and must be valid.
       - `release` is used for params that are handles or pointers to handles where the function will decrement the handle's reference count, potentially leaving it in an invalid state if the reference count reaches zero.
       - `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.

scripts/YaML.md

@@ -34,7 +34,7 @@ params:
     - type: "$x_adapter_handle_t*"
       name: phAdapters
       desc: |
-            [out][optional][range(0, NumEntries)] array of handle of adapters.
+            [out][optional][range(0, NumEntries)][alloc] array of handle of adapters.
             If NumEntries is less than the number of adapters available, then $xAdapterGet shall only retrieve that number of adapters.
     - type: "uint32_t*"
       name: "pNumAdapters"

scripts/core/adapter.yml

@@ -59,7 +59,7 @@ params:
             [in][optional] pointer to context creation properties.
     - type: $x_context_handle_t*
       name: phContext
-      desc: "[out] pointer to handle of context object created"
+      desc: "[out][alloc] pointer to handle of context object created"
 returns:
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
     - $X_RESULT_ERROR_OUT_OF_DEVICE_MEMORY
@@ -243,7 +243,7 @@ params:
     - type: "$x_context_handle_t*"
       name: phContext
       desc: |
-            [out] pointer to the handle of the context object created.
+            [out][alloc] pointer to the handle of the context object created.
 returns:
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If the adapter has no underlying equivalent handle."

scripts/core/context.yml

@@ -136,7 +136,7 @@ params:
     - type: "$x_device_handle_t*"
       name: phDevices
       desc: |
-            [out][optional][range(0, NumEntries)] array of handle of devices.
+            [out][optional][range(0, NumEntries)][alloc] array of handle of devices.
             If NumEntries is less than the number of devices available, then platform shall only retrieve that number of devices.
     - type: "uint32_t*"
       name: pNumDevices
@@ -834,7 +834,7 @@ params:
       desc: "[in][optional] pointer to native device properties struct."
     - type: "$x_device_handle_t*"
       name: phDevice
-      desc: "[out] pointer to the handle of the device object created."
+      desc: "[out][alloc] pointer to the handle of the device object created."
 returns:
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If the adapter has no underlying equivalent handle."

scripts/core/device.yml

@@ -317,7 +317,7 @@ params:
     - type: "$x_event_handle_t*"
       name: phEvent
       desc: |
-            [out] pointer to the handle of the event object created.
+            [out][alloc] pointer to the handle of the event object created.
 returns:
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If the adapter has no underlying equivalent handle."

scripts/core/enqueue.yml

@@ -429,7 +429,7 @@ params:
       desc: "[in] pointer to image description"
     - type: $x_exp_image_mem_native_handle_t*
       name: phImageMem
-      desc: "[out] pointer to handle of image memory allocated"
+      desc: "[out][alloc] pointer to handle of image memory allocated"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -484,7 +484,7 @@ params:
       desc: "[in] pointer to image description"
     - type: $x_exp_image_native_handle_t*
       name: phImage
-      desc: "[out] pointer to handle of image object created"
+      desc: "[out][alloc] pointer to handle of image object created"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -522,7 +522,7 @@ params:
       desc: "[in] sampler to be used"
     - type: $x_exp_image_native_handle_t*
       name: phImage
-      desc: "[out] pointer to handle of image object created"
+      desc: "[out][alloc] pointer to handle of image object created"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -583,7 +583,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [out][optional] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
+            [out][optional][alloc] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
 returns:
     - $X_RESULT_ERROR_INVALID_QUEUE
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -699,7 +699,7 @@ params:
       desc: "[in] the external memory descriptor"
     - type: $x_exp_external_mem_handle_t*
       name: phExternalMem
-      desc: "[out] external memory handle to the external memory"
+      desc: "[out][alloc] external memory handle to the external memory"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -812,7 +812,7 @@ params:
       desc: "[in] the external semaphore descriptor"
     - type: $x_exp_external_semaphore_handle_t*
       name: phExternalSemaphore
-      desc: "[out] external semaphore handle to the external semaphore"
+      desc: "[out][alloc] external semaphore handle to the external semaphore"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -872,7 +872,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [out][optional] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
+            [out][optional][alloc] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
 returns:
     - $X_RESULT_ERROR_INVALID_QUEUE
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -911,7 +911,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [out][optional] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
+            [out][optional][alloc] return an event object that identifies this particular command instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
 returns:
     - $X_RESULT_ERROR_INVALID_QUEUE
     - $X_RESULT_ERROR_INVALID_VALUE

scripts/core/event.yml

@@ -285,7 +285,7 @@ params:
       desc: "[in][optional] command-buffer descriptor."
     - type: "$x_exp_command_buffer_handle_t*"
       name: phCommandBuffer
-      desc: "[out] Pointer to command-Buffer handle."
+      desc: "[out][alloc] Pointer to command-Buffer handle."
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_DEVICE
@@ -386,10 +386,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command. Only available if the
+      desc: "[out][optional][alloc] Handle to this command. Only available if the
       command-buffer is updatable."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
@@ -451,10 +451,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_SIZE:
@@ -513,10 +513,10 @@ params:
       desc: "[out][optional] sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_SIZE:
@@ -580,10 +580,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -639,10 +639,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -698,10 +698,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -772,10 +772,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -846,10 +846,10 @@ params:
       desc: "[out][optional] Sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -982,10 +982,10 @@ params:
       desc: "[out][optional] sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -1043,10 +1043,10 @@ params:
       desc: "[out][optional] sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -1106,10 +1106,10 @@ params:
       desc: "[out][optional] sync point associated with this command."
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
+      desc: "[out][optional][alloc] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
     - type: "$x_exp_command_buffer_command_handle_t*"
       name: phCommand
-      desc: "[out][optional] Handle to this command."
+      desc: "[out][optional][alloc] Handle to this command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
@@ -1152,7 +1152,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [out][optional] return an event object that identifies this particular command-buffer execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
+            [out][optional][alloc] return an event object that identifies this particular command-buffer execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_INVALID_QUEUE
@@ -1213,7 +1213,7 @@ params:
       desc: "[in] Handle of the command-buffer command to update."
     - type: "$x_event_handle_t*"
       name: phSignalEvent
-      desc: "[out] Event to be signaled."
+      desc: "[out][alloc] Event to be signaled."
 returns:
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`."

scripts/core/exp-bindless-images.yml

@@ -55,7 +55,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [out][optional] return an event object that identifies this particular kernel execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
+            [out][optional][alloc] return an event object that identifies this particular kernel execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array.
 returns:
     - $X_RESULT_ERROR_INVALID_QUEUE
     - $X_RESULT_ERROR_INVALID_KERNEL

scripts/core/exp-command-buffer.yml

@@ -111,7 +111,7 @@ params:
       desc: "[in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event. "
     - type: $x_event_handle_t*
       name: phEvent
-      desc: "[out][optional] return an event object that identifies this particular kernel execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array."
+      desc: "[out][optional][alloc] return an event object that identifies this particular kernel execution instance. If phEventWaitList and phEvent are not NULL, phEvent must not refer to an element of the phEventWaitList array."
 returns:
     - $X_RESULT_SUCCESS
     - $X_RESULT_ERROR_UNINITIALIZED