Improved lifetime handling and docs of loader

* The loader now checks that all handles have been released before
  dropping factories.
* Some arguments of functions have been marked as [alloc]. When the
  loader generates a handle from them, they will have an initial
  reference count that requires a single release.
* Handles that are assigned to non-alloc pointers must exist and their
  reference counts are not incremented.

Author: RossBrunton

include/ur_api.h

@@ -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

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
@@ -832,7 +832,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

@@ -581,7 +581,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
@@ -870,7 +870,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
@@ -909,7 +909,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

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

scripts/core/exp-bindless-images.yml

@@ -37,7 +37,7 @@ decl: static
 params:
     - type: $x_loader_config_handle_t*
       name: phLoaderConfig
-      desc: "[out] Pointer to handle of loader config object created."
+      desc: "[out][alloc] Pointer to handle of loader config object created."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Get a reference to the loader config object."

scripts/core/kernel.yml

@@ -229,7 +229,7 @@ params:
       desc: "[in][optional] pointer to native platform properties struct."
     - type: "$x_platform_handle_t*"
       name: phPlatform
-      desc: "[out] pointer to the handle of the platform object created."
+      desc: "[out][alloc] pointer to the handle of the platform object created."
 returns:
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If the adapter has no underlying equivalent handle."