Re: [edk2-InfSpecification PATCH v2] Document: Add new MODULE_TYPE HOST_APPLICATION

["Liming Gao" <liming.gao@intel.com>]

Reviewed-by: Liming Gao <liming.gao@intel.com>

>-----Original Message-----
>From: Lu, XiaoyuX
>Sent: Friday, July 05, 2019 3:43 PM
>To: devel@edk2.groups.io
>Cc: Lu, XiaoyuX <xiaoyux.lu@intel.com>; Gao, Liming <liming.gao@intel.com>;
>Yao, Jiewen <jiewen.yao@intel.com>
>Subject: [edk2-InfSpecification PATCH v2] Document: Add new
>MODULE_TYPE HOST_APPLICATION
>
>BZ: https://bugzilla.tianocore.org/show_bug.cgi?id=1952
>
>Background:
>Host-based Firmware Analyzer (HBFA) is a opensouce tools enables advanced
>testing of UEFI and UEFI PI drivers in developer's OS environment. It
>will generate OS application which can run directly in OS environment. But
>there is no explicit MODULE_TYPE to indicate those modules.
>
>Difference:
>USER_DEFINED can be anyting, execuatable file, bin, acpi table, etc.
>HOST_APPLICATION identify it is a executable file.
>
>Add HOST_APPLICATION module type so it's easier to identify.
>
>Cc: Liming Gao <liming.gao@intel.com>
>Cc: Jiewen Yao <jiewen.yao@intel.com>
>Signed-off-by: Xiaoyu Lu <xiaoyux.lu@intel.com>
>---
> 1_introduction/12_terms.md                              | 4 ++--
> 2_inf_overview/215_[depex]_section.md                   | 4 ++--
> 2_inf_overview/26_[buildoptions]_section.md             | 2 +-
> 3_edk_ii_inf_file_format/314_[depex]_sections.md        | 7 ++++---
> 3_edk_ii_inf_file_format/32_component_inf_definition.md | 4 +++-
> 3_edk_ii_inf_file_format/34_[defines]_section.md        | 6 ++++--
> README.md                                               | 3 ++-
> appendix_f_module_types.md                              | 1 +
> 8 files changed, 19 insertions(+), 12 deletions(-)
>
>diff --git a/1_introduction/12_terms.md b/1_introduction/12_terms.md
>index 14827fd..ba96813 100644
>--- a/1_introduction/12_terms.md
>+++ b/1_introduction/12_terms.md
>@@ -232,8 +232,8 @@ with a similar set of requirements. A module that is of
>module type `BASE`,
> depends only on headers and libraries provided in the MDE, while a module
>that
> is of module type DXE_DRIVER depends on common DXE components. For a
>definition
> of the various module types, see module type. The EDK II build system also
>-permits modules of type `USER_DEFINED`. These modules will not be
>processed by
>-the EDK II Build system.
>+permits modules of type `USER_DEFINED` and `HOST_APPLICATION`. These
>modules
>+will not be processed by the EDK II Build system.
>
> **Package**
>
>diff --git a/2_inf_overview/215_[depex]_section.md
>b/2_inf_overview/215_[depex]_section.md
>index 912228f..a710cae 100644
>--- a/2_inf_overview/215_[depex]_section.md
>+++ b/2_inf_overview/215_[depex]_section.md
>@@ -72,8 +72,8 @@ Additionally, the rules for specifying DEPEX sections are
>as follows.
>   `DXE_SMM_DRIVER` to generate an `SMM_DEPEX` section.
>
> * If the ModuleType is `SEC`, `UEFI_APPLICATION`, `UEFI_DRIVER`,
>`PEI_CORE`,
>-  `SMM_CORE` or `DXE_CORE`, no `[Depex]` sections are permitted and all
>library
>-  class `[Depex]` sections are ignored.
>+  `SMM_CORE`, `DXE_CORE`, `HOST_APPLICATION`, no `[Depex]` sections are
>+  permitted and all library class `[Depex]` sections are ignored.
>
> * Module types `PEIM`, `DXE_DRIVER`, `DXE_RUNTIME_DRIVER`,
>`DXE_SAL_DRIVER` and
>   `DXE_SMM_DRIVER` require a `[Depex]` section unless the dependencies
>are
>diff --git a/2_inf_overview/26_[buildoptions]_section.md
>b/2_inf_overview/26_[buildoptions]_section.md
>index 667d8d9..5e9059c 100644
>--- a/2_inf_overview/26_[buildoptions]_section.md
>+++ b/2_inf_overview/26_[buildoptions]_section.md
>@@ -74,7 +74,7 @@ shown above.
> | `TAGNAME`   | YES        | Yes = *    | `Conf/tools_def.txt` file defines several
>different tag names - these are defined by developers; the default tag name,
>`MYTOOLS`, is provided in the template for tools_def.txt and set in the
>`Conf/target.txt` file.                      |
> | `ARCH`      | YES        | Yes = *    | `Conf/tools_def.txt` defines at least four
>architectures: `IA32`, `X64` and `EBC`. This tag must use all capital letters for
>the tag. Additional Architectures, such as PPC or ARM may be added as
>support becomes available.        |
> | `TOOLCODE`  | YES        | NO         | The tool code must be one of the defined
>tool codes in the `Conf/tools_def.txt` file. The flags defined in this section are
>appended to flags defined in the `tools_def.txt` file for individual tools.
>|
>-|             |            |            | EXCEPTION: If the INF `MODULE_TYPE`, defined in the
>`[Defines]` section is `USER_DEFINED`, then the flags listed in this section are
>the only flags used for the TOOLCODE command specified in `Conf/
>tools_def.txt`.                       |
>+|             |            |            | EXCEPTION: If the INF `MODULE_TYPE`, defined in
>the `[Defines]` section is `USER_DEFINED` or `HOST_APPLICATION`, then the
>flags listed in this section are the only flags used for the TOOLCODE command
>specified in `Conf/ tools_def.txt`.                       |
> | `ATTRIBUTE` | YES        | NO         | The attribute must be specific to the tool
>code and must be a valid attribute handled by the build system.
>|
>
> Developers should use extreme caution when specifying items in this section.
>diff --git a/3_edk_ii_inf_file_format/314_[depex]_sections.md
>b/3_edk_ii_inf_file_format/314_[depex]_sections.md
>index 02d5bb4..75b0139 100644
>--- a/3_edk_ii_inf_file_format/314_[depex]_sections.md
>+++ b/3_edk_ii_inf_file_format/314_[depex]_sections.md
>@@ -120,9 +120,10 @@ section.
>
> If the module is not a library (no `LIBRARY_CLASS` in the `[Defines]` section)
> and the `MODULE_TYPE` is `SEC`, `SMM_CORE`, `DXE_CORE`, `PEI_CORE`,
>-`UEFI_DRIVER` or `UEFI_APPLICATION` a Depex section is not permitted. If
>one is
>-found, the build tools must exit gracefully and provide the user with an error
>-message stating the `[Depex]` section is not valid for the `MODULE_TYPE`
>+`UEFI_DRIVER`, `UEFI_APPLICATION` or `HOST_APPLICATION` a Depex
>section is
>+not permitted. If one is found, the build tools must exit gracefully and
>+provide the user with an error message stating the `[Depex]` section is not
>+valid for the `MODULE_TYPE`
>
> If the module is a library (with a `LIBRARY_CLASS` statement in the `[Defines]`
> section) and there is no module type defined in Depex section's modifier and
>diff --git a/3_edk_ii_inf_file_format/32_component_inf_definition.md
>b/3_edk_ii_inf_file_format/32_component_inf_definition.md
>index b80218b..164771c 100644
>--- a/3_edk_ii_inf_file_format/32_component_inf_definition.md
>+++ b/3_edk_ii_inf_file_format/32_component_inf_definition.md
>@@ -62,7 +62,8 @@ EBNF).
>                  if (LIBRARY_CLASS is declared in Defines Section):
>                    <Depex>*
>                  elif (MODULE_TYPE == "USER_DEFINED"
>-                       || MODULE_TYPE == "UEFI_DRIVER"):
>+                       || MODULE_TYPE == "UEFI_DRIVER"
>+                       || MODULE_TYPE == "HOST_APPLICATION"):
>                           <Depex>*
>                  elif (MODULE_TYPE == "PEIM"
>                        || MODULE_TYPE == "DXE_DRIVER"
>@@ -257,6 +258,7 @@ The following are common definitions used by multiple
>section types.
>                           {"DXE_RUNTIME_DRIVER"} {"DXE_SAL_DRIVER"}
>                           {"DXE_SMM_DRIVER"} {"UEFI_DRIVER"}
>                           {"UEFI_APPLICATION"} {"USER_DEFINED"}
>+                          {"HOST_APPLICATION"}
> <ModuleTypeList>      ::= <ModuleType> [" " <ModuleType>]*
> <IdentifierName>      ::= <TS> {<MACROVAL>} {<PcdName>} <TS>
> <Boolean>             ::= {<BoolType>} {<Expression>}
>diff --git a/3_edk_ii_inf_file_format/34_[defines]_section.md
>b/3_edk_ii_inf_file_format/34_[defines]_section.md
>index 69be2b0..78ac58d 100644
>--- a/3_edk_ii_inf_file_format/34_[defines]_section.md
>+++ b/3_edk_ii_inf_file_format/34_[defines]_section.md
>@@ -191,8 +191,10 @@ the `MODULE_UNI_FILE` entry must be a Unicode file
>with an extension of .uni,
> Drivers and applications are not allowed to have a `MODULE_TYPE` of
>`"BASE`".
> Only libraries are permitted to a have a `MODULE_TYPE` of `"BASE`". A INF file
> can be used to specify other binary files types, such as logo images or
>-legacy16 option ROMs. The `USER_DEFINED` module type must be used in all
>cases
>-where the module type is not a member of `<Edk2ModuleType>`.
>+legacy16 option ROMs. `HOST_APPLICATION` module should be used to
>sepcify host
>+application that can run in OS environment directly. The `USER_DEFINED`
>module type
>+must be used in all cases where the module type is not a member of
>+`<Edk2ModuleType>`.
>
> **_INF_VERSION_**
>
>diff --git a/README.md b/README.md
>index 6819441..60fba19 100644
>--- a/README.md
>+++ b/README.md
>@@ -201,4 +201,5 @@ Copyright (c) 2007-2017, Intel Corporation. All rights
>reserved.
> |            | Add clarification that !error statement is not permitted in INF file
>|               |
> |            | INF Spec: FixedAtBuild (VOID*) PCD use in the [DEPEX] section
>|               |
> |            | [#1162](https://bugzilla.tianocore.org/show_bug.cgi?id=1162)
>Correct the item in Table 1 to align with 3.4 section
>|               |
>-| 1.28       | [#1453](https://bugzilla.tianocore.org/show_bug.cgi?id=1453)
>Update INF spec to remove EDK related contents
>| Mar 2019      |
>\ No newline at end of file
>+| 1.28       | [#1453](https://bugzilla.tianocore.org/show_bug.cgi?id=1453)
>Update INF spec to remove EDK related contents
>| Mar 2019      |
>+| 1.29       | [#1952](https://bugzilla.tianocore.org/show_bug.cgi?id=1952)
>Add new MODULE_TYPE HOST_APPLICATION
>| July 2019      |
>diff --git a/appendix_f_module_types.md b/appendix_f_module_types.md
>index 7082332..f7c2200 100644
>--- a/appendix_f_module_types.md
>+++ b/appendix_f_module_types.md
>@@ -57,6 +57,7 @@
> | UEFI_DRIVER                | UEFI_DRIVER
>| .efi             | This module type is used by UEFI Drivers that are compliant with
>the EFI 1.10 Specification or the UEFI 2.x Specification. These modules provide
>services in the boot services execution environment. UEFI Drivers that return
>EFI_SUCCESS are not unloaded from memory. UEFI Drivers that return an
>error are unloaded from memory.
>|
> | UEFI_APPLICATION           | UEFI_APPLICATION
>| .efi             | This module type is used by UEFI Applications that are compliant
>with the EFI 1.10 Specification or the UEFI 2.x Specification. UEFI Applications
>are always unloaded when they exit.
>|
> | USER_DEFINED               | USER_DEFINED
>| .bin or .rom     | User defined extension
>|
>+| HOST_APPLICATION           | HOST_APPLICATION
>| .exe or NULL     | This module type is for building applications which can run
>in host OS directly.
>|
> | EFI Dependency Section     | Any - the code for these sections is included as
>part of any module, and no separate INF is required.
>| .dpx             | This is the compiled dependency section for SMM, PEIM or DXE
>modules. A dependency section may also be generated from a dependency
>source (.dxs) file, if specified in the `[Sources]` section.
>|
> | EFI User Interface Section | Any - the code for these sections is included as
>part of any module, and no separate INF is required.
>| .ui              | This is a processed User Interface section
>|
> | EFI Version Section        | Any - the code for these sections is included as part
>of any module, and no separate INF is required.
>| .ver             | This is a processed Version section |
>--
>2.17.1