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>

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."