config_tools: add placeholders in input widgets

The configurator today shows "Please Input" as the placeholder of input
widgets, which is far from informative.

This patch specifies element or type specific placeholders in the XML
schema by reusing the `acrn:widget-options` annotation mechanism. For
manually-designed widgets such as ivshmem or vUART the placeholders are
added in the corresponding vue directly.

Tracked-On: #6691
Signed-off-by: Junjie Mao <junjie.mao@intel.com>

doc/scripts/configdoc.xsl

@@ -5,7 +5,7 @@
   <xsl:variable name="section_adornment" select="'#*=-%+@`'"/>
   <xsl:variable name="vLower" select="'abcdefghijklmnopqrstuvwxyz'"/>
   <xsl:variable name="vUpper" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
-  <!-- xslt script to autogenerate config option documentation -->  
+  <!-- xslt script to autogenerate config option documentation -->
   <!-- Get things started with the ACRNConfigType element -->
   <xsl:template match="/xs:schema">
     <xsl:apply-templates select="xs:complexType[@name='ACRNConfigType']">
@@ -204,6 +204,11 @@
           <xsl:with-param name="indent" select="'     '"/>
         </xsl:call-template>
       </xsl:when>
+      <xsl:when test="starts-with(xs:restriction/@base, 'xs:')">
+        <xsl:variable name="ty" select="xs:restriction/@base"/>
+        <xsl:value-of select="concat(translate(substring($ty, 4,1), $vLower, $vUpper), substring($ty,5),' value')"/>
+        <xsl:value-of select="$newline"/>
+      </xsl:when>
       <xsl:otherwise>
         <xsl:text>No type annotation found</xsl:text>
         <xsl:value-of select="$newline"/>

misc/config_tools/configurator/packages/configurator/src/pages/Config/ConfigForm/CustomWidget/IVSHMEM_REGION.vue

@@ -9,7 +9,7 @@
             <label>Region name: </label>
           </b-col>
           <b-col md="4">
-            <b-form-input v-model="IVSHMEM_VMO.NAME"/>
+            <b-form-input v-model="IVSHMEM_VMO.NAME" placeholder="Any string with no white spaces."/>
           </b-col>
         </b-row>
 
@@ -48,7 +48,7 @@
               <b-form-select v-model="IVSHMEM_VM.VM_NAME" :options="vmNames"></b-form-select>
             </b-col>
             <b-col sm="3">
-              <b-form-input v-model="IVSHMEM_VM.VBDF"/>
+              <b-form-input v-model="IVSHMEM_VM.VBDF" placeholder="00:[device].[function], e.g. 00:0c.0. All fields are in hexadecimal."/>
             </b-col>
             <b-col sm="3">
               <div class="ToolSet">

misc/config_tools/configurator/packages/configurator/src/pages/Config/ConfigForm/CustomWidget/VUART.vue

@@ -50,15 +50,15 @@
           <b-row class="justify-content-sm-start align-items-center">
             <b-col sm="4"> Connection_{{ index + 1 }}-{{ VUARTConn.endpoint[0].vm_name }} </b-col>
             <b-col sm="4">
-              <b-form-input v-model="VUARTConn.endpoint[0].io_port" v-if="VUARTConn.type === 'legacy'"/>
+              <b-form-input v-model="VUARTConn.endpoint[0].io_port" v-if="VUARTConn.type === 'legacy'" placeholder="An address in hexadecimal, e.g. 0x4000"/>
-              <b-form-input v-model="VUARTConn.endpoint[0].vbdf" v-else-if="VUARTConn.type === 'pci'"/>
+              <b-form-input v-model="VUARTConn.endpoint[0].vbdf" v-else-if="VUARTConn.type === 'pci'" placeholder="00:[device].[function], e.g. 00:1c.0. All fields are in hexadecimal."/>
             </b-col>
           </b-row>
           <b-row class="justify-content-sm-start align-items-center">
             <b-col sm="4"> Connection_{{ index + 1 }}-{{ VUARTConn.endpoint[1].vm_name }} </b-col>
             <b-col sm="4">
-              <b-form-input v-model="VUARTConn.endpoint[1].io_port" v-if="VUARTConn.type === 'legacy'"/>
+              <b-form-input v-model="VUARTConn.endpoint[1].io_port" v-if="VUARTConn.type === 'legacy'" placeholder="An address in hexadecimal, e.g. 0x4000"/>
-              <b-form-input v-model="VUARTConn.endpoint[1].vbdf" v-else-if="VUARTConn.type === 'pci'"/>
+              <b-form-input v-model="VUARTConn.endpoint[1].vbdf" v-else-if="VUARTConn.type === 'pci'" placeholder="00:[device].[function], e.g. 00:1c.0. All fields are in hexadecimal."/>
             </b-col>
           </b-row>
         </div>

misc/config_tools/scenario_config/jsonschema/converter.py

@@ -148,8 +148,8 @@ class XS2JS:
     def convert_widget_config(self, annotation, js_ele):
         if '@acrn:widget' in annotation:
             js_ele['ui:widget'] = annotation['@acrn:widget']
-            if '@acrn:widget-options' in annotation:
+        if '@acrn:widget-options' in annotation:
-                js_ele['ui:options'] = {eval(k): eval(v) for k, v in [kv.split('=') for kv in annotation['@acrn:widget-options'].split(',')]}
+            js_ele['ui:options'] = eval(f"{{{annotation['@acrn:widget-options']}}}")
 
     def xst2jst(self, type_name) -> str:
         """convert xml schema type name to json schema type name"""
@@ -195,9 +195,9 @@ class XS2JS:
                             enum_names.append(enum_name)
                     js_st["enumNames"] = enum_names
 
-                # widget and its options
+            # widget and its options
-                if 'xs:annotation' in obj:
+            if 'xs:annotation' in obj:
-                    self.convert_widget_config(obj['xs:annotation'], js_st)
+                self.convert_widget_config(obj['xs:annotation'], js_st)
 
             js_st.update(self.xsa2jsa(restriction))
             return js_st
@@ -297,12 +297,14 @@ class XS2JS:
                 required.append(name)
 
             if '@maxOccurs' in element:
-                possible_keys = ['type', '$ref', 'oneOf']
+                # ui:options seen at this moment are copied from the annotation of the type.
+                possible_keys = ['type', '$ref', 'oneOf', 'ui:options']
                 convert_to_items_success = False
+                js_ele['items'] = {}
                 for possible_key in possible_keys:
                     if possible_key not in js_ele:
                         continue
-                    js_ele['items'] = {possible_key: js_ele[possible_key]}
+                    js_ele['items'][possible_key] = js_ele[possible_key]
                     del js_ele[possible_key]
                     convert_to_items_success = True
 

misc/config_tools/schema/VMtypes.xsd

@@ -147,17 +147,20 @@ The size is a subset of the VM's total memory size specified on the Basic tab.</
       </xs:annotation>
     </xs:element>
     <xs:element name="kern_mod" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="Kernel module tag">
+      <xs:annotation acrn:title="Kernel module tag"
+                     acrn:widget-options="'placeholder': 'An arbitrary string without white spaces. The same string shall be appended, in grub.conf, to the GRUB module containing the OS kernel.'">
         <xs:documentation>Specify the tag for the kernel image that is used as a multiboot module. The tag's spelling must exactly match the module tag in the GRUB multiboot cmdline.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="ramdisk_mod" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="RAMdisk module tag">
+      <xs:annotation acrn:title="RAMdisk module tag"
+                     acrn:widget-options="'placeholder': '(Optional) An arbitrary string without white spaces. The same string shall be appended, in grub.conf, to the GRUB module containing the OS ramdisk or initrd.'">
         <xs:documentation>Specify the tag for the RAMdisk image that is used as a multiboot module. The tag's spelling must exactly match the module tag in the GRUB multiboot cmdline.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="bootargs" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="Kernel command-line parameters">
+      <xs:annotation acrn:title="Kernel command-line parameters"
+                     acrn:widget-options="'placeholder': '(Optional) The command line options to be passed to the OS kernel.'">
         <xs:documentation>Specify the command-line parameters that will be used to boot the kernel for this VM. See `Linux documentation &lt;https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html&gt;`__ for a list of parameters.</xs:documentation>
       </xs:annotation>
     </xs:element>
@@ -276,8 +279,7 @@ The size is a subset of the VM's total memory size specified on the Basic tab.</
 <xs:complexType name="PCIDevsConfiguration">
   <xs:sequence>
     <xs:element name="pci_dev" type="xs:string" minOccurs="0" maxOccurs="unbounded">
-      <xs:annotation acrn:title="PCI device assignment"
+      <xs:annotation acrn:options="//device[class]/@description" acrn:options-sorted-by="lambda s: (s.split(' ', maxsplit=1)[-1].split(':')[0], s.split(' ')[0])">
-		     acrn:options="//device[class]/@description" acrn:options-sorted-by="lambda s: (s.split(' ', maxsplit=1)[-1].split(':')[0], s.split(' ')[0])">
         <xs:documentation>Select the PCI devices you want to assign to this virtual machine.</xs:documentation>
       </xs:annotation>
     </xs:element>
@@ -314,13 +316,13 @@ The size is a subset of the VM's total memory size specified on the Basic tab.</
       </xs:annotation>
     </xs:element>
     <xs:element name="interface_name" minOccurs="0">
-      <xs:annotation acrn:title="Network interface name">
+      <xs:annotation acrn:title="Network interface name" acrn:widget-options="'placeholder': 'An arbitrary-long string with letters, digits, underscores or dashes.'">
         <xs:documentation>Specify the network interface name that will appear in the Service VM. Use the `ip a` command in the Service VM to display the network interface names.</xs:documentation>
       </xs:annotation>
       <xs:simpleType>
-  <xs:annotation>
+        <xs:annotation>
-       <xs:documentation>A string of letters, digits, ``_``, or ``-``.</xs:documentation>
+          <xs:documentation>A string of letters, digits, ``_``, or ``-``.</xs:documentation>
-  </xs:annotation>
+        </xs:annotation>
         <xs:restriction base="xs:string">
           <xs:pattern value="[a-zA-Z0-9_\-]+" />
         </xs:restriction>
@@ -372,18 +374,18 @@ device file when user config it as virtio serial port, which can be read and wri
         <xs:documentation>Specify backend device type in service VM.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="output_file_path" type="xs:string" minOccurs="0" maxOccurs="1">
+    <xs:element name="output_file_path" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="Output file path">
+      <xs:annotation acrn:title="Output file path" acrn:widget-options="'placeholder': '/home/user/path/to/console_output.txt, needed only when backend type is file.'">
         <xs:documentation>The output file path for the file backend type.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="sock_file_path" type="xs:string" minOccurs="0" maxOccurs="1">
+    <xs:element name="sock_file_path" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="Sock file path">
+      <xs:annotation acrn:title="Sock file path" acrn:widget-options="'placeholder': '/path/to/file.sock, needed only when backend type is sock client or server.'">
         <xs:documentation>The sock file path for the sock server or client backend type.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="tty_device_path" type="xs:string" minOccurs="0" maxOccurs="1">
+    <xs:element name="tty_device_path" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="TTY device path">
+      <xs:annotation acrn:title="TTY device path" acrn:widget-options="'placeholder': '/dev/ttyX, needed only when backend type is tty.'">
         <xs:documentation>The device path for the tty backend type.</xs:documentation>
       </xs:annotation>
     </xs:element>
@@ -393,12 +395,12 @@ device file when user config it as virtio serial port, which can be read and wri
 <xs:complexType name="VirtioInputConfiguration">
   <xs:sequence>
     <xs:element name="backend_device_file" type="xs:string" minOccurs="0">
-      <xs:annotation acrn:title="Backend device file">
+      <xs:annotation acrn:title="Backend device file" acrn:widget-options="'placeholder': '/dev/input/eventX'">
         <xs:documentation>Specifying backend device in service vm with device description.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="id" minOccurs="0">
-      <xs:annotation acrn:title="Guest virtio input device unique identifier">
+      <xs:annotation acrn:title="Guest virtio input device unique identifier" acrn:widget-options="'placeholder': 'An arbitrary-long string with letters, digits, underscores or dashes.'">
         <xs:documentation>Specifying unique identifier to distinguish same devices in guest.</xs:documentation>
       </xs:annotation>
       <xs:simpleType>

misc/config_tools/schema/config.xsd

@@ -286,7 +286,7 @@ These settings can only be changed at build time.</xs:documentation>
 Refer to :ref:`vuart_config` for detailed vUART settings.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="CACHE_REGION" type="CacheRegionType" minOccurs="0" maxOccurs="1">
+    <xs:element name="CACHE_REGION" type="CacheRegionType" minOccurs="0">
       <xs:annotation>
         <xs:documentation>Specify the cache setting.</xs:documentation>
       </xs:annotation>
@@ -306,20 +306,10 @@ Refer to :ref:`vuart_config` for detailed vUART settings.</xs:documentation>
         <xs:documentation>Select the VM type. A standard VM (``STANDARD_VM``) is for general-purpose applications, such as human-machine interface (HMI). A real-time VM (``RTVM``) offers special features for time-sensitive applications.</xs:documentation>
       </xs:annotation>
     </xs:element>
-    <xs:element name="name">
+    <xs:element name="name" type="VMNameType">
         <xs:annotation acrn:title="VM name" acrn:views="basic">
           <xs:documentation>Specify the name used to identify this VM. The VM name will be shown in the hypervisor console vm_list command.</xs:documentation>
         </xs:annotation>
-      <xs:simpleType>
-        <xs:annotation>
-          <xs:documentation>A string from 1 to 32 characters long (with no spaces).</xs:documentation>
-        </xs:annotation>
-        <xs:restriction base="xs:string">
-          <xs:minLength value="1" />
-          <xs:maxLength value="15" />
-          <xs:pattern value="\S+" />
-        </xs:restriction>
-      </xs:simpleType>
     </xs:element>
     <xs:element name="lapic_passthrough" type="Boolean" default="n" minOccurs="0">
       <xs:annotation acrn:title="LAPIC passthrough" acrn:applicable-vms="pre-launched, post-launched" acrn:views="advanced">
@@ -404,7 +394,7 @@ argument and memory.</xs:documentation>
       </xs:annotation>
     </xs:element>
     <xs:element name="mmio_resources" type="MMIOResourcesConfiguration" minOccurs="0">
-      <xs:annotation acrn:applicable-vms="pre-launched" acrn:views="basic">
+      <xs:annotation acrn:title="MMIO Resources" acrn:applicable-vms="pre-launched" acrn:views="basic">
         <xs:documentation>MMIO resources to passthrough.</xs:documentation>
       </xs:annotation>
     </xs:element>
@@ -470,13 +460,18 @@ is the virtio network driver, simulating the virtual NIC. The backend could be:
 mouse, and tablet.  It sends Linux input layer events over virtio.</xs:documentation>
 	        </xs:annotation>
 	      </xs:element>
-          <xs:element name="block" type="xs:string" minOccurs="0" maxOccurs="unbounded">
+          <xs:element name="block" minOccurs="0" maxOccurs="unbounded">
             <xs:annotation acrn:title="Virtio block device" acrn:views="basic">
               <xs:documentation>The virtio-blk device presents a block device to the VM. Each virtio-blk device appears as a disk inside the VM.</xs:documentation>
             </xs:annotation>
+              <xs:simpleType>
+                  <xs:annotation acrn:widget-options="'placeholder': '/home/user/path/to/disk.image'" />
+                  <xs:restriction base="xs:string" />
+              </xs:simpleType>
           </xs:element>
           <xs:element name="gpu" type="xs:string" minOccurs="0">
-            <xs:annotation acrn:title="Virtio GPU device" acrn:views="basic">
+            <xs:annotation acrn:title="Virtio GPU device" acrn:views="basic"
+                           acrn:widget-options="'placeholder': 'fullscreen or geometry=[width]x[height]+[x offset]+[y offset], e.g. geometry=1280x720+0+0 specifies a 1280 x 720 pixels region at the top left corner of the screan'">
               <xs:documentation>The virtio GPU device presents a GPU device to the VM.
 This feature enables you to view the VM's GPU output in the Service VM.</xs:documentation>
             </xs:annotation>

misc/config_tools/schema/types.xsd

@@ -4,7 +4,7 @@
 	   xmlns:acrn="https://projectacrn.org">
 
 <xs:simpleType name="Boolean">
-  <xs:annotation acrn:widget="b-form-checkbox" acrn:widget-options="'value' = 'y', 'unchecked-value' = 'n'">
+  <xs:annotation acrn:widget="b-form-checkbox" acrn:widget-options="'value': 'y', 'unchecked-value': 'n'">
     <xs:documentation>A Boolean value, written as ``y`` or ``n``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
@@ -24,7 +24,7 @@
 </xs:simpleType>
 
 <xs:simpleType name="HexFormat">
-  <xs:annotation>
+  <xs:annotation acrn:widget-options="'placeholder': 'A hexadecimal number with a leading 0x, e.g. 0x1000.'">
     <xs:documentation>An Integer value in hexadecimal format (with a leading ``0x``).</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">
@@ -184,7 +184,7 @@ Read more about the available scheduling options in :ref:`cpu_sharing`.</xs:docu
 </xs:simpleType>
 
 <xs:simpleType name="VMNameType">
-  <xs:annotation>
+  <xs:annotation acrn:widget-options="'placeholder': 'A string with at most 15 non-space characters, e.g. Linux-VM-1.'">
     <xs:documentation>A string of up to 15 letters, digits, ``_``, or ``-``.</xs:documentation>
   </xs:annotation>
   <xs:restriction base="xs:string">