Specify what state kernel objects are in after a failed call to clSetKernelArg (#705)

* Specify what state kernel objects are in after a failed call to clSetKernelArg

Fixes #548

Signed-off-by: Kevin Petit <kevin.petit@arm.com>
Change-Id: Ibcc63c7f6e19bff4169c22e16f3ff4dacf2b6e25

* address review comments

Change-Id: I04665e6cbb60577d427e58b90464418e58cefbe5

Author: kpet

api/footnotes.asciidoc

@@ -162,3 +162,7 @@ Only once the ID has been allotted may it be exposed to OpenCL by proposing a me
 The merge must define a new enumerant by adding an `<enum>` tag to the {cl_khronos_vendor_id_TYPE} `<enums>` tag, with the `<value>` attribute set as the acquired Khronos vendor ID. \
 The `<name>` attribute must identify the vendor/adopter, and be of the form `CL_KHRONOS_VENDOR_ID_<vendor>`. \
 ]
+
+:fn-setkernelarg-prefer-unset-on-error: pass:n[ \
+Implementations are encouraged to favor this option as it makes it more likely that errors will be managed by applications. \
+]

api/opencl_runtime_layer.asciidoc

@@ -7219,6 +7219,16 @@ Otherwise, it returns one of the following errors:
     by the OpenCL implementation on the device.
   * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
     required by the OpenCL implementation on the host.
+
+When {clSetKernelArg} returns an error code different from {CL_SUCCESS}, the
+internal state of _kernel_ may only be modified when that error code is
+{CL_OUT_OF_RESOURCES} or {CL_OUT_OF_HOST_MEMORY}. When the internal state
+of _kernel_ is modified, it is implementation-defined whether:
+
+  * The argument value that was previously set is kept so that it can be used in
+    further kernel enqueues.
+  * The argument value is unset such that a subsequent kernel enqueue fails with
+    {CL_INVALID_KERNEL_ARGS}. footnote:[{fn-setkernelarg-prefer-unset-on-error}]
 --
 
 [open,refpage='clSetKernelArgSVMPointer',desc='Set a SVM pointer as the argument value for a specific argument of a kernel.',type='protos']