Add Pretty Name to Config XML (#351)

## Description Add a pretty name field to the XML knobs to allow an easier time to read the configuration knobs per feature request #350 . For each item, place an "x" in between `[` and `]` if true. Example: `[x]`. _(you can also check items in the GitHub UI)_ - [ ] Impacts functionality? - **Functionality** - Does the change ultimately impact how firmware functions? - Examples: Add a new library, publish a new PPI, update an algorithm, ... - [ ] Impacts security? - **Security** - Does the change have a direct security impact on an application, flow, or firmware? - Examples: Crypto algorithm change, buffer overflow fix, parameter validation improvement, ... - [ ] Breaking change? - **Breaking change** - Will anyone consuming this change experience a break in build or boot behavior? - Examples: Add a new library class, move a module to a different repo, call a function in a new library class in a pre-existing module, ... - [ ] Includes tests? - **Tests** - Does the change include any explicit test code? - Examples: Unit tests, integration tests, robot tests, ... - [ ] Includes documentation? - **Documentation** - Does the change contain explicit documentation additions outside direct code modifications (and comments)? - Examples: Update readme file, add feature readme file, link to documentation on an a separate Web page, ... ## How This Was Tested Tested with the updated sampleschema.xml ## Integration Instructions If desired, the prettyname field can be added to existing XMLs. This will not break existing XMLs.
microsoft · May 22, 2024 · 3d2bcc4 · 3d2bcc4
1 parent ad7737d
commit 3d2bcc4
Show file tree

Hide file tree

Showing 7 changed files with 51 additions and 23 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -124,6 +124,7 @@
       "ANYSIZE",
       "profilenames",
       "profileid",
-      "profileids"
+      "profileids",
+      "prettyname"
   ]
 }
diff --git a/SetupDataPkg/SetupDataPkg.ci.yaml b/SetupDataPkg/SetupDataPkg.ci.yaml
@@ -90,7 +90,8 @@
           "privilege",
           "dmpstore",
           "mschange",
-          "DDTHH"
+          "DDTHH",
+          "prettyname"
         ],                           # words to extend to the dictionary for this package
         "IgnoreStandardPaths": [],   # Standard Plugin defined paths that should be ignore
         "AdditionalIncludePaths": [] # Additional paths to spell check (wildcards supported)

diff --git a/SetupDataPkg/Tools/GenNCCfgData.py b/SetupDataPkg/Tools/GenNCCfgData.py
@@ -105,7 +105,7 @@ def get_cfg_item_options(self, item):
         if item["type"].upper() == "ENUM_KNOB":
             if type(item["inst"].format) is not EnumFormat:
                 raise Exception("The item is malformed!!!")
-            tmp_list = [i.name for i in item["inst"].format.values]
+            tmp_list = [i.pretty_name for i in item["inst"].format.values]
         elif item["type"].upper() == "BOOL_KNOB":
             if type(item["inst"].format) is not BoolFormat:
                 raise Exception("The item is malformed!!!")
@@ -158,25 +158,31 @@ def build_cfg_list(self):
 
         # Add the pages for each root knob
         for knob in self.schema.knobs:
+            # try to use pretty name if it exists
+            print_name = knob.pretty_name
+            if print_name == '':
+                print_name = knob.name
             if not self.add_cfg_page(
                 child=".".join([knob.namespace, knob.name]),
                 parent=knob.namespace,
-                title=knob.name,
+                title=print_name,
             ):
                 # The parent page may not exist yet
                 self.add_cfg_page(child=knob.namespace, parent=self._cur_page, title=knob.namespace)
                 if not self.add_cfg_page(
                     child=".".join([knob.namespace, knob.name]),
                     parent=knob.namespace,
-                    title=knob.name,
+                    title=print_name,
                 ):
                     raise Exception("Failed to add page for knob %s" % knob.name)
 
         ret_list = []
         # below is a shim layer that connects the UI and data structure
         for idx, data in enumerate(self.schema.subknobs):
             itype = type(data.format)
-            name = data.name
+            name = data.pretty_name
+            if name == '':
+                name = data.name
             ord_dict = OrderedDict()
             if itype is IntValueFormat:
                 ord_dict["type"] = "INTEGER_KNOB"
@@ -195,9 +201,9 @@ def build_cfg_list(self):
             ord_dict["inst"] = data
             ord_dict["order"] = idx
             ord_dict["name"] = name
-            ord_dict["cname"] = name
+            ord_dict["cname"] = data.name
             ord_dict["value"] = data.format.object_to_string(data.value)
-            ord_dict["path"] = ".".join([data.knob.namespace, name])
+            ord_dict["path"] = ".".join([data.knob.namespace, data.name])
             ord_dict["help"] = data.help
             ret_list.append(ord_dict)
 

diff --git a/SetupDataPkg/Tools/GenNCCfgData_test.py b/SetupDataPkg/Tools/GenNCCfgData_test.py
@@ -113,7 +113,7 @@ def test_xml_get_cfg_list(self):
         # Get only a struct knob
         ret = cdata.get_cfg_list('FE3ED49F-B173-41ED-9076-356661D46A42.COMPLEX_KNOB1a')
         self.assertGreater(len(ret), 1)
-        self.assertEqual(ret[0]['name'], 'COMPLEX_KNOB1a')
+        self.assertEqual(ret[0]['name'], 'Complex knob')
         self.assertEqual(ret[0]['type'], 'STRUCT_KNOB')
         self.assertEqual(cdata.schema.get_knob(
             "FE3ED49F-B173-41ED-9076-356661D46A42", "COMPLEX_KNOB1a"), ret[0]['inst'])
@@ -171,7 +171,7 @@ def test_xml_reformat_value_str(self):
 
         # Run on an enum knob
         ret = cdata.get_item_by_path('FE3ED49F-B173-41ED-9076-356661D46A42.COMPLEX_KNOB1b.mode')
-        val_str = 'THIRD'
+        val_str = 'Third Mode'
         self.assertEqual(ret['type'], 'ENUM_KNOB')
         ret_str = cdata.reformat_value_str(val_str, cdata.get_cfg_item_length(ret), item=ret)
         self.assertEqual(val_str, ret_str)
@@ -232,7 +232,7 @@ def test_xml_set_item_value(self):
 
         # Run on an enum knob
         ret = cdata.get_item_by_path('FE3ED49F-B173-41ED-9076-356661D46A42.COMPLEX_KNOB1b.mode')
-        val_str = 'THIRD'
+        val_str = 'Third Mode'
         self.assertEqual(ret['type'], 'ENUM_KNOB')
         ret_str = cdata.set_item_value(val_str, item=ret)
         self.assertEqual(ret_str, val_str)
@@ -274,7 +274,7 @@ def test_xml_get_cfg_item_options(self):
         ret = cdata.get_item_by_path('FE3ED49F-B173-41ED-9076-356661D46A42.COMPLEX_KNOB1b.mode')
         self.assertEqual(ret['type'], 'ENUM_KNOB')
         ret_list = cdata.get_cfg_item_options(item=ret)
-        self.assertEqual(ret_list, ["FIRST", "SECOND", "THIRD"])
+        self.assertEqual(ret_list, ["First Mode", "Second Mode", "Third Mode"])
 
         # Run on a boolean knob
         ret = cdata.get_item_by_path('FE3ED49F-B173-41ED-9076-356661D46A42.BOOLEAN_KNOB')

diff --git a/SetupDataPkg/Tools/VariableList.py b/SetupDataPkg/Tools/VariableList.py
@@ -300,6 +300,9 @@ class EnumValue:
     def __init__(self, enum_name, xml_node):
         self.enum_name = enum_name
         self.name = xml_node.getAttribute("name")
+        self.pretty_name = xml_node.getAttribute("prettyname")
+        if self.pretty_name == '':
+            self.pretty_name = self.name
         if not is_valid_name(self.name):
             raise InvalidNameError(
                 "Enum '{}' has invalid value name '{}'".format(
@@ -322,6 +325,9 @@ def __init__(self, enum_name, xml_node):
 class EnumFormat(DataFormat):
     def __init__(self, xml_node):
         self.name = xml_node.getAttribute("name")
+        self.pretty_name = xml_node.getAttribute("prettyname")
+        if self.pretty_name == '':
+            self.pretty_name = self.name
         if not is_valid_name(self.name):
             raise InvalidNameError(
                 "Enum name '{}' is invalid".format(self.name))
@@ -360,7 +366,7 @@ def string_to_object(self, string_representation, eval_context=StringEvaluationC
             return int(string_representation)
         except ValueError:
             for value in self.values:
-                if value.name == string_representation:
+                if value.name == string_representation or value.pretty_name == string_representation:
                     return value.number
         raise ParseError(
             "Value '{}' is not a valid value of enum '{}'".format(
@@ -376,7 +382,7 @@ def object_to_string(
                 if options.c_format:
                     return "{}_{}".format(self.name, value.name)
                 else:
-                    return value.name
+                    return value.pretty_name
         return str(object_representation)
 
     def object_to_binary(self, object_representation):
@@ -501,6 +507,7 @@ def check_bounds(self, value, min, max):
 class StructMember:
     def __init__(self, schema, struct_name, xml_node):
         self.name = xml_node.getAttribute("name")
+        self.pretty_name = xml_node.getAttribute("prettyname")
         self.struct_name = struct_name
         if not is_valid_name(self.name):
             raise InvalidNameError(
@@ -566,6 +573,7 @@ def check_bounds(self, value, min, max):
 class StructFormat(DataFormat):
     def __init__(self, schema, xml_node):
         self.name = xml_node.getAttribute("name")
+        self.pretty_name = xml_node.getAttribute("prettyname")
         if not is_valid_name(self.name):
             raise InvalidNameError("Struct name '{}' is invalid".format(
                 self.name))
@@ -601,7 +609,7 @@ def __init__(self, schema, xml_node):
 
     def create_subknobs(self, knob, path):
         subknobs = []
-        subknobs.append(SubKnob(knob, path, self, self.help))
+        subknobs.append(SubKnob(knob, path, self, self.help, self.pretty_name))
         for member in self.members:
             subpath = "{}.{}".format(path, member.name)
             if member.count == 1:
@@ -614,6 +622,7 @@ def create_subknobs(self, knob, path):
                             subpath,
                             member.format,
                             member.help,
+                            member.pretty_name,
                             True  # Leaf
                         ))
             else:
@@ -623,6 +632,7 @@ def create_subknobs(self, knob, path):
                         subpath,
                         member.format,
                         member.help,
+                        member.pretty_name,
                         False  # Leaf
                     ))
 
@@ -639,6 +649,7 @@ def create_subknobs(self, knob, path):
                                 indexed_subpath,
                                 member.format.format,
                                 member.help,
+                                member.pretty_name,
                                 True  # Leaf
                             ))
         return subknobs
@@ -731,6 +742,7 @@ def check_bounds(self, value, min, max):
 class Knob:
     def __init__(self, schema, xml_node, namespace):
         self.name = xml_node.getAttribute("name")
+        self.pretty_name = xml_node.getAttribute("prettyname")
         if not is_valid_name(self.name):
             raise InvalidNameError(
                 "Knob name '{}' is invalid".format(self.name))
@@ -792,6 +804,7 @@ def __init__(self, schema, xml_node, namespace):
                     self,
                     self.name,
                     self.format,
+                    self.pretty_name,
                     self.help))
             self.subknobs += self.format.create_subknobs(self, self.name)
         else:
@@ -801,6 +814,7 @@ def __init__(self, schema, xml_node, namespace):
                     self.name,
                     self.format,
                     self.help,
+                    self.pretty_name,
                     True  # Leaf
                 ))
 
@@ -917,9 +931,10 @@ def _decode_subpath(self, subpath_segment):
 
 
 class SubKnob:
-    def __init__(self, knob, path, format, help, leaf=False):
+    def __init__(self, knob, path, format, help, pretty_name, leaf=False):
         self.knob = knob
         self.name = path
+        self.pretty_name = pretty_name
         self.format = format
         self.help = help
         self.leaf = leaf

diff --git a/SetupDataPkg/Tools/configschema.xsd b/SetupDataPkg/Tools/configschema.xsd
@@ -12,13 +12,15 @@
                     <xs:element name="Value" maxOccurs="unbounded">
                       <xs:complexType>
                         <xs:attribute name="name" use="required" />
+                        <xs:attribute name="prettyname" use="optional" />
                         <xs:attribute name="value" use="required" />
                         <xs:attribute name="help" use="optional" />
                         <xs:attribute name="deprecated" type="xs:boolean" use="optional" />
                       </xs:complexType>
                     </xs:element>
                   </xs:sequence>
                   <xs:attribute name="name" use="required" />
+                  <xs:attribute name="prettyname" use="optional" />
                   <xs:attribute name="default" use="optional" />
                   <xs:attribute name="help" use="optional" />
                 </xs:complexType>
@@ -35,6 +37,7 @@
                     <xs:element name="Member" maxOccurs="unbounded">
                       <xs:complexType>
                         <xs:attribute name="name" use="required" />
+                        <xs:attribute name="prettyname" use="optional" />
                         <xs:attribute name="type" use="required" />
                         <xs:attribute name="default" use="optional" />
                         <xs:attribute name="min" use="optional" />
@@ -46,6 +49,7 @@
                     </xs:element>
                   </xs:sequence>
                   <xs:attribute name="name" use="required" />
+                  <xs:attribute name="prettyname" use="optional" />
                   <xs:attribute name="help" use="optional" />
                 </xs:complexType>
               </xs:element>
@@ -59,6 +63,7 @@
                 <xs:element name="Knob" maxOccurs="unbounded">
                   <xs:complexType>
                     <xs:attribute name="name" use="required" />
+                    <xs:attribute name="prettyname" use="optional" />
                     <xs:attribute name="type" use="required" />
                     <xs:attribute name="default" use="optional" />
                     <xs:attribute name="min" use="optional" />

diff --git a/SetupDataPkg/Tools/sampleschema.xml b/SetupDataPkg/Tools/sampleschema.xml
@@ -5,18 +5,18 @@
        The same Enum can be used as the 'enumtype' of any number of EnumKnobs -->
   <Enums>
     <Enum name="OPTION_MODE" help="Modes of the option">
-      <Value name="FIRST" value="0" help="First mode" />
-      <Value name="SECOND" value="1" help="Second mode" />
-      <Value name="THIRD" value="2" help="Third mode" />
+      <Value name="FIRST" prettyname="First Mode" value="0" help="First mode" />
+      <Value name="SECOND" prettyname="Second Mode" value="1" help="Second mode" />
+      <Value name="THIRD" prettyname="Third Mode" value="2" help="Third mode" />
     </Enum>
   </Enums>
 
   <Structs>
     <Struct name="simple_t" help="Simple struct">
       <Member name="value" count="2" type="uint32_t" />
     </Struct>
-    <Struct name="child_t" help="Embedded struct">
-      <Member name="data" type="uint8_t" count="5" help="Bytes" />
+    <Struct name="child_t" prettyname="Child Struct"  help="Embedded struct">
+      <Member name="data" prettyname="child Data" type="uint8_t" count="5" help="Bytes" />
       <Member name="mode" type="OPTION_MODE" />
     </Struct>
     <Struct name="sample_t" help="Sample struct">
@@ -31,12 +31,12 @@
 
     <Knob name="COMPLEX_KNOB1a" type="child_t" default="{{1,2,3, 4,5 },FIRST }" help="Complex knob" />
 
-    <Knob name="COMPLEX_KNOB1b" type="child_t" default="{{1,2,3, 4,5 },SECOND }" help="Complex type" />
+    <Knob name="COMPLEX_KNOB1b" prettyname="Complex Knob 1b Struct" type="child_t" default="{{1,2,3, 4,5 },SECOND }" help="Complex type" />
 
     <Knob name="COMPLEX_KNOB2" type="sample_t" default="{2,{{{1,2,3, 4,5 },FIRST },{{6,7,8, 9,10 },SECOND }}}" help="Complex type" />
 
     <Knob name="INTEGER_KNOB" type="uint32_t" default="100" help="Integer type" />
-    <Knob name="BOOLEAN_KNOB" type="bool" default="true" help="Boolean type" />
+    <Knob name="BOOLEAN_KNOB" prettyname="Boolean Knob"  type="bool" default="true" help="Boolean type" />
     <Knob name="DOUBLE_KNOB" type="double" default="3.1415926" help="Double type" />
     <Knob name="FLOAT_KNOB" type="float" default="1.414" help="Float type" />