Misc. patches to v1.9 release (#278)

- Add missing enumerations to programming guides
- Add numWaitEvents parameter to mutable command list update wait events API (needed for loader)
- Add range to phCommandLists description in append command lists extension
- Fix spelling error in sysman subdevice properties structure type name
- Fix immediate command list append API parameter description to work around script limitation
- Convert fixed-length character array parameters to constant pointers in programmable metrics and firmware security version extensions

Signed-off-by: Will Damon <will.damon@intel.com>

Author: wdamon-intel

scripts/core/EXT_Exp_CommandListClone.rst

@@ -17,6 +17,10 @@ from templates import helper as th
 API
 ----
 
+* Enumerations
+
+    * ${x}_command_list_clone_exp_version_t
+
 * Functions
 
     * ${x}CommandListCreateCloneExp

scripts/core/EXT_Exp_ImmediateCommandListAppend.rst

@@ -17,6 +17,10 @@ from templates import helper as th
 API
 ----
 
+* Enumerations
+
+    * ${x}_immediate_command_list_append_exp_version_t
+
 * Functions
 
     * ${x}CommandListImmediateAppendCommandListsExp

scripts/core/EXT_Exp_MutableCommandList.rst

@@ -176,7 +176,7 @@ The application may subsequently mutate specific commands, as follows:
     ${x}CommandListUpdateMutableCommandSignalEventExp(hCommandList, commandId, hNewLaunchKernelSignalEvent);
 
     // Update the wait events for the launch kernel command
-    ${x}CommandListUpdateMutableCommandWaitEventsExp(hCommandList, commandId, &hNewLaunchKernelWaitEvent);
+    ${x}CommandListUpdateMutableCommandWaitEventsExp(hCommandList, commandId, 1, &hNewLaunchKernelWaitEvent);
 
     // Close the command list
     ${x}CommandListClose(hCommandList);

scripts/core/immediateCommandListAppend.yml

@@ -44,7 +44,7 @@ params:
       desc: "[in] number of command lists"
     - type: "$x_command_list_handle_t*"
       name: phCommandLists
-      desc: "[in] handle(s) of command list(s)"
+      desc: "[in][range(0, numCommandLists)] handles of command lists"
     - type: $x_event_handle_t
       name: hSignalEvent
       desc: |

scripts/core/mutableCommandList.yml

@@ -264,6 +264,12 @@ params:
     - type: uint64_t
       name: commandId
       desc: "[in] command identifier"
+    - type: uint32_t
+      name: numWaitEvents
+      desc: "[in][optional] the number of wait events"
     - type: "$x_event_handle_t*"
       name: phWaitEvents
       desc: "[in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching"
+returns:
+    - $X_RESULT_ERROR_INVALID_SIZE:
+       - "The `numWaitEvents` parameter does not match that of the original command."

scripts/sysman/EXT_Exp_FirmwareSecurityVersion.rst

@@ -37,7 +37,7 @@ higher SVN for security considerations.
 
     // Fetch current security version from the fuses
     char* version = allocate(version_size);
-    ${s}FirmwareGetSecurityVersionExp(hFirmware, &version);
+    ${s}FirmwareGetSecurityVersionExp(hFirmware, version);
 
     // Set security version
     ${s}FirmwareSetSecurityVersionExp(hFirmware);

scripts/sysman/common.yml

@@ -229,7 +229,7 @@ etors:
       value: "0x00020003"
       desc: $s_mem_page_offline_state_exp_t
       version: "1.8"
-    - name: SUB_DEVICE_EXP_PROPERTIES 
+    - name: SUBDEVICE_EXP_PROPERTIES 
       value: "0x00020004"
       desc: $s_subdevice_exp_properties_t
       version: "1.9"

scripts/sysman/firmwareSecurityVersion.yml

@@ -31,15 +31,16 @@ version: "1.9"
 class: $sFirmware
 name: GetSecurityVersionExp
 details:
+    - "The application should create a character array of size $S_STRING_PROPERTY_SIZE and reference it for the `pVersion` parameter."
     - "The application may call this function from simultaneous threads."
     - "The implementation of this function should be lock-free."
 params:
     - type: $s_firmware_handle_t
       name: hFirmware
       desc: "[in] Handle for the component."
-    - type: char
-      name: "version[$S_STRING_PROPERTY_SIZE]"
-      desc: "[out] NULL terminated string value. The string \"unknown\" will be returned if this property cannot be determined."
+    - type: "char*"
+      name: "pVersion"
+      desc: "[in,out] NULL terminated string value. The string \"unknown\" will be returned if this property cannot be determined."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Set the firmware security version number"

scripts/tools/metricProgrammable.yml

@@ -352,12 +352,12 @@ params:
     - type: uint32_t
       name: parameterCount
       desc: "[in] Count of parameters to set."
-    - type: const char
-      name: "name[ZET_MAX_METRIC_NAME]"
-      desc: "[in] Metric name to be used."
-    - type: const char
-      name: "description[ZET_MAX_METRIC_DESCRIPTION]"
-      desc: "[in] Metric description to be used."
+    - type: "const char*"
+      name: "pName"
+      desc: "[in] pointer to metric name to be used. Must point to a null-terminated character array no longer than $T_MAX_METRIC_NAME."
+    - type: "const char*"
+      name: "pDescription"
+      desc: "[in] pointer to metric description to be used. Must point to a null-terminated character array no longer than $T_MAX_METRIC_DESCRIPTION."
     - type: "uint32_t*"
       name: pMetricHandleCount
       desc: |
@@ -382,12 +382,12 @@ params:
     - type: $t_device_handle_t
       name: hDevice
       desc: "[in] handle of the device"
-    - type: const char
-      name: name[ZET_MAX_METRIC_GROUP_NAME]
-      desc: "[in] Metric group name."
-    - type: const char
-      name: description[ZET_MAX_METRIC_GROUP_DESCRIPTION]
-      desc: "[in] Metric group description."
+    - type: "const char*"
+      name: pName
+      desc: "[in] pointer to metric group name. Must point to a null-terminated character array no longer than $T_MAX_METRIC_GROUP_NAME."
+    - type: "const char*"
+      name: pDescription
+      desc: "[in] pointer to metric group description. Must point to a null-terminated character array no longer than $T_MAX_METRIC_GROUP_DESCRIPTION."
     - type: $t_metric_group_sampling_type_flags_t
       name: samplingType
       desc: "[in] Sampling type for the metric group."