Required changes to KnobService and XML Schema to enable per-library …

…header definitions and XML merging (#357)

# Preface

Please ensure you have read the [contribution
docs](https://github.com/microsoft/mu/blob/master/CONTRIBUTING.md) prior
to submitting the pull request. In particular,
[pull request
guidelines](https://github.com/microsoft/mu/blob/master/CONTRIBUTING.md#pull-request-best-practices).

## Description

Add a header reference field to the XML definitions to allow flexible
build inclusion patterns.

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 locally updated sampleschema.xml.
Tested end-to-end with SCP firmware.

## Integration Instructions

'headerRef' is an optional attribute that, when used, is consumed by
KnobService to reference headers instead of generating the 'Enum' and
'Struct' type definitions in-place. This attribute will not breaking
existing XMLs.

---------

Co-authored-by: Mario Posso Escobar <[email protected]>

.cspell.json

@@ -128,6 +128,11 @@
       "prettyname",
       "efivars",
       "efivarfs",
-      "chattr"
+      "chattr",
+      "typesonly",
+      "nochange",
+      "headerRef",
+      "modea",
+      "modeb"
   ]
 }

SetupDataPkg/Docs/ConfigurationFiles/ConfigurationFiles.md

@@ -73,14 +73,24 @@ A `Enums` block can be added to define enums (which resolve to INT32s) for a pla
       <Value name="SECOND" value="1" help="Second mode" />
       <Value name="THIRD" value="2" help="Third mode" />
     </Enum>
+    <Enum name="MODULE_MODE" headerRef="module_defs.h" help="Module modes">
+      <Value name="MODEA" prettyname="Mode A" value="0" help="Fast mode" />
+      <Value name="MODEB" prettyname="Mode B" value="1" help="Slow mode" />
+    </Enum>
   </Enums>
 ```
 
+Enums can be optionally marked by a `headerRef` attribute for build topologies that wish to directly borrow library/module
+definitions in configuration schemas. In the example above, Enum `MODULE_MODE` will function as normal, with the exception
+that the generated headers that reference this Enum will _not_ declare its type and will instead directly `#include` the
+attributed `headerRef`. For more information on the generated headers, see [here](../PlatformIntegration/PlatformIntegrationSteps.md#autogenerated-header-files).
+
 ### User Defined Structs
 
 A `<Structs>` block can be added to define structures for a platform, as shown below. These structs can have basic types,
 enums, and other structs as members. Structs are packed into the `CONFIG_VAR_LIST_HDR` (and comments within for
 the variable length pieces of the structure) structure defined [here](../../Include/Library/ConfigVariableListLib.h).
+Structs, like Enums, can also be attributed a `headerRef` reference to yield the same effect described above.
 
 ```xml
   <Structs>
@@ -91,7 +101,7 @@ the variable length pieces of the structure) structure defined [here](../../Incl
       <Member name="data" type="uint8_t" count="5" help="Bytes" />
       <Member name="mode" type="OPTION_MODE" />
     </Struct>
-    <Struct name="sample_t" help="Sample struct">
+    <Struct name="sample_t" headerRef="module_defs.h" help="Sample struct">
       <Member name="counter" type="uint32_t" help="Number value" />
       <Member name="children" type="child_t" count="2" help="Child data" />
     </Struct>

SetupDataPkg/Docs/PlatformIntegration/PlatformIntegrationSteps.md

@@ -129,7 +129,9 @@ There are four autogenerated headers and one standard structure definition heade
 
 The PlatformConfigDataLib includes, in this order, the standard structure definition header, the client header, the
 data header, and the profile header (if profiles are used). In this way the structure and enum definitions are
-populated before the data and profile headers attempt to use them.
+populated before the data and profile headers attempt to use them. Note that these definitions may be `#include`d in
+instead of declared in-file dependent upon the schema's usage of the optional `headerRef` attribute, and care must be
+taken for the consuming build system to be aware of the implicit pathing requirement to all attributed `headerRef`s.
 
 The OEM platform config policy creator only include the standard structure definition header so that it can operate on
 the `KNOB_DATA` and `PROFILE` structures with generic data.
@@ -154,6 +156,28 @@ when the modules are XIP (execute in place).
 The Silicon Policy Consumers do not need to include any of the above headers and will instead fetch their configuration
 directly from silicon policy.
 
+#### KnobService
+
+The four generated headers described in the **Autogenerated Header Files** section above are produced by KnobService.
+For more information on tool usage, please refer to the following tool help text below:
+
+***generateheader[_efi] <schema.xml> <public_header.h> <service_header.h> [<data_header.h>] [<profile_header.h> <profile.csv>...]***
+
+- *schema.xml*: An XML with the definition of a set of known config knobs and types to interpret them.
+- *public_header.h*: Output header for use by config consumers.
+- *service_header.h*: Output header for use by config provider. In UEFI builds this only contains getter implementations.
+- *data_header.h*: Output header for UEFI builds only. This contains only the data. In non-UEFI builds, service_header.h
+and data_header.h are combined.
+- *profile_header.h*: Output header for the profile data for consumption by config providers.
+- *profile.csv...*: n-number of profile csvs that describe the platform's overridden config knobs.
+- *pn names*: n-number of 2-character profile names that uniquely identify the profiles specified in profile.csv.
+- *pid ids*: n-number of 1-byte hexadecimal (prepend with 0x) profile id that uniquely identify the profiles specified
+in profile.csv.
+- *-t*: Option flag to enable 'types only' outputting, forcing the generation of *public_header.h* with Enum/Struct type
+declarations only. *service_header.h* generation is skipped if this option is used.
+- *-nc*: Option flag to enable 'no change' behavior which disables any type name modifications from the input schema.
+All names become passthrough.
+
 ### Config Knob Validation Functions
 
 The Project Mu XML based configuration provides an OEM/platform with the ability to provide config knob validation