Re: [Patch] INF spec: Correct some items in the Table 1 EDK II [Defines] Section

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

Yonghong:
  Please list which items are corrected in the commit message. 

Thanks
Liming
>-----Original Message-----
>From: Zhu, Yonghong
>Sent: Friday, September 07, 2018 3:08 PM
>To: edk2-devel@lists.01.org
>Cc: Gao, Liming <liming.gao@intel.com>; Kinney, Michael D
><michael.d.kinney@intel.com>; Shaw, Kevin W <kevin.w.shaw@intel.com>
>Subject: [Patch] INF spec: Correct some items in the Table 1 EDK II [Defines]
>Section
>
>Fixes: https://bugzilla.tianocore.org/show_bug.cgi?id=1162
>Cc: Liming Gao <liming.gao@intel.com>
>Cc: Michael Kinney <michael.d.kinney@intel.com>
>Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
>Contributed-under: TianoCore Contribution Agreement 1.1
>Signed-off-by: Yonghong Zhu <yonghong.zhu@intel.com>
>---
> 2_inf_overview/24_[defines]_section.md           | 59 ++++++++++++------------
> 3_edk_ii_inf_file_format/34_[defines]_section.md |  2 +-
> README.md                                        |  1 +
> 3 files changed, 31 insertions(+), 31 deletions(-)
>
>diff --git a/2_inf_overview/24_[defines]_section.md
>b/2_inf_overview/24_[defines]_section.md
>index 37b0135..0afdfed 100644
>--- a/2_inf_overview/24_[defines]_section.md
>+++ b/2_inf_overview/24_[defines]_section.md
>@@ -106,35 +106,34 @@ the PEI Core or the Dxe Core. EDK II only references
>the first possible
> dispatch instance.
> **********
>
> ###### Table 1 EDK II [Defines] Section Elements
>
>-| Tag                          | Required                                                                 | Value
>| Notes
>|
>-| ---------------------------- | -------------------------------------------------------------
>----------- | --------------------------------------------- | ----------------------------------
>-----------------------------------------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>--------------------- |
>-| `INF_VERSION`                | REQUIRED                                                                 | 1.27 or
>0x0001001B                            | This identifies the INF spec. version. It is decimal
>value with fraction or two-nibble hexadecimal representation of the same, for
>example: 1.27. Tools use this value to handle parsing of previous releases of
>the specification if there are incompatible changes.
>|
>-| `BASE_NAME`                  | REQUIRED                                                                 | A
>single word                                 | This is a single word identifier that will be used
>for the component name.
>|
>-| `EDK_RELEASE_VERSION`        | Not required                                                             |
>Hex Double Word                               | The minimum revision value across the
>module and all its dependent libraries. If a revision value is not declared in the
>module or any of the dependent libraries, then the tool may use the value of
>0, which disables checking.
>|
>-| `PI_SPECIFICATION_VERSION`   | Not required
>| Decimal or special format of hex              | The minimum revision value across
>the module and all its dependent libraries. If a revision value is not declared in
>the module or any of the dependent libraries, then tools may use the value of
>0, which disables checking.
>|
>-|                              |                                                                          |
>| The `PI_SPECIFICATION_VERSION` must only be set in the INF file if the
>module depends on services or system table fields or PI core behaviors that
>are not present in the PI 1.0 version. For example, if a module depends on
>definitions in PI 1.1 that are not in PI 1.0, then `PI_SPECIFICATION_VERSION`
>must be 0x0001000A
>|
>-| `UEFI_SPECIFICATION_VERSION` | Not required
>| Decimal or special format of hex              | The minimum revision value across
>the module and all its dependent libraries. If a revision value is not declared in
>the module or any of the dependent libraries, then tools may use the value of
>0, which disables checking.
>|
>-|                              |                                                                          |
>| The `UEFI_SPECIFICATION_VERSIon` must only be set in the INF file if the
>module depends on UEFI Boot Services or UEFI Runtime Services or UEFI
>System Table fields or UEFI core behaviors that are not present in the UEFI 2.1
>version. For example, if a module depends on definitions in UEFI 2.2 that are
>not in UEFI 2.1, then `UEFI_SPECIFICATION_VERSION` must be 0x00020014
>|
>-| `FILE_GUID`                  | REQUIRED                                                                 | GUID
>Value                                    | Registry (8-4-4-4-12) Format This value is required for
>all EDK II format INF files, required for EDK driver INF files, not required for
>EDK libraries
>|
>-| `MODULE_TYPE`                | REQUIRED                                                                 |
>| This is the type of module. One of the EDK II Module Types. For Library
>Modules, the `MODULE_TYPE` must specify the `MODULE_TYPE` of the
>module that will use the driver.
>|
>-| `BUILD_NUMBER`               | Optional                                                                 |
>UINT16 Value                                  | This optional element, if present (or set in the
>DSC file), is used during the creation of the `EFI_VERSION_SECTION` for this
>module; if it is not present, then the BuildNumber field of the
>`EFI_VERSION_SECTION` will be set to 0.
>|
>-| `VERSION_STRING`             | REQUIRED                                                                 |
>String                                        | If present, this value will be encoded as USC-2
>characters in a Unicode file for the VERSION section of the FFS unless a ver or
>ver_ui file has been specified in the `[Binaries]` section.
>|
>-| `MODULE_UNI_FILE`            | Optional                                                                 |
>Filename                                      | A Unicode file containing UCS-2 character
>localization strings; the file path (if present) is relative to the directory
>containing the INF file. The use of #include statements in this file is prohibited.
>|
>-| `LIBRARY_CLASS`              | Typically not specified for a Driver; REQUIRED for a
>Library Only Module | Word &#124; List ["&#124;" Word &#124; List]* | One
>Library Class that is satisfied by this Library Instance; one or more
>`LIBRARY_CLASS` lines may be specified by a module. The reserved keyword,
>NULL, must be listed for library class instances that do NOT support a library
>class keyword.
>|
>-| `PCD_IS_DRIVER`              | Not required - Driver Only
>| PEI_PCD_DRIVER or DXE_PCD_DRIVER              | Only required for the two
>(PEI_PCD_DRIVER or DXE_PCD_DRIVER) PCD Driver modules.
>|
>-| `ENTRY_POINT`                | Not required - Driver Only                                               |
>CName                                         | This is the name of the driver's entry point
>function.
>|
>-| `UNLOAD_IMAGE`               | Not required - Driver Only
>| CName                                         | If a driver chooses to be unloadable, then this
>is the name of the module's function registered in the Loaded Image Protocol.
>It is called if the UEFI Boot Service UnloadImage() is called for the module,
>which then executes the Unload function, disconnecting itself from handles in
>the database as well as uninstalling any protocols that were installed in the
>driver entry point. The CName is the name of this module's unload function. |
>-| `CONSTRUCTOR`                | Not required - Library Only
>| CName                                         | This only applies to components that are
>libraries. It is required for EDK II libraries if the module's INF contains a
>Constructor element. This value is used to call the specified function before
>calling into the library itself.
>|
>-| `DESTRUCTOR`                 | Not required - Library Only                                              |
>CName                                         | This only applies to components that are libraries.
>This value is used to call the specified function before calling into the library
>itself.
>|
>-| `SHADOW`                     | Not required - SEC, PEIM and PEI_CORE Driver
>modules only                | TRUE &#124; FALSE                             | This boolean
>operator is used by `SEC`, `PEI_CORE` and `PEIM` modules to indicate if the
>module was coded to use `REGISTER_FOR_SHADOW`. If the value is TRUE,
>the .reloc section of the PE32 image is not removed, otherwise, the .reloc
>section is stripped to conserve space in the final binary images. The default
>value is FALSE.                                                                                                              |
>-| `PCI_DEVICE_ID`              | Not required - Required for UEFI PCI Option ROMs
>| Hex Number                                    | The PCI Device Id for this device.
>|
>-| `PCI_VENDOR_ID`              | Not required - Required for UEFI PCI Option
>ROMs                         | Hex Number                                    | The PCI Vendor Id for this
>device
>|
>-| `PCI_CLASS_CODE`             | Not required - Required for UEFI PCI Option
>ROMs                         | Hex Number                                    | The PCI Class Code for
>this device
>|
>-| `PCI_COMPRESS`               | Not required UEFI PCI Option ROMs
>| TRUE &#124; FALSE                             | This flag is used by tools to compress a
>PCI Option ROM image file, the default (if not specified) is FALSE
>|
>-| `UEFI_HII_RESOURCE_SECTION`  | Not required Driver Only
>| TRUE &#124; FALSE                             | This boolean operator is used to indicate
>that the module will require a separate HII resource section in the efi image
>file.
>|
>-| `DEFINE`                     | Not required                                                             | Name =
>Value                                  | The value must be a directory name, and the name
>can be used with $( and ) character sets. This allows shortening of lines typed
>by users.
>|
>-| `SPEC`                       | Not required                                                             | CName =
>Value                                 | A User-specified #define CName Value pair that will
>be included in the `AutoGen.h` file.
>|
>-| `CUSTOM_MAKEFILE`            | Not required                                                             |
>Family &#124; File                            | A user written makefile that will be used,
>the INF file will not be parsed.  The Family is one of MSFT or GCC followed by a
>field separator "&#124;" character, then the filename of the makefile in the
>same directory as the INF file. To keep GCC compatibility, the user must
>generate two Makefiles, one for MSFT, such as makefile and another for GCC,
>such as GNUmakefile                                                                   |
>-| `DPX_SOURCE`                 | Not Required Driver Only                                                 |
>Filename                                      | If present, the file must contain all DEPEX
>statements (as defined in the UEFI PI specification), as the tools will process
>the file, ignoring any content in `[Depex]` sections in this file AND all inherited
>dependencies from libraries. This allows the module owner to force a Depex
>independently. Use of this option is not recommended for normal use.
>|
>+|Tag                         |Required                                                     |Value                           |
>Notes
>|
>+|----------------------------|-------------------------------------------------------------
>|--------------------------------|------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>-----------------------------------------------------------------------------------------------
>------------------- ---------------|
>+|`INF_VERSION`               |REQUIRED                                                     |1.27 or
>0x0001001B              | This identifies the INF spec version. It is decimal value
>with fraction or two-nibble hexadecimal representation of the same, for
>example: 1.27. Tools use this value to handle parsing of previous releases of
>the specification if there are incompatible changes.
>|
>+|`BASE_NAME`                 |REQUIRED                                                     |A single word
>| This is a single word identifier that will be used for the component name.
>|
>+|`PI_SPECIFICATION_VERSION`  |Not required
>|Decimal or special format of hex| The minimum revision value across the
>module and all its dependent libraries. If a revision value is not declared in the
>module or any of the dependent libraries, then tools may use the value of 0,
>which disables checking.
>|
>+|                            |                                                             |                                | The
>`PI_SPECIFICATION_VERSION` must only be set in the INF file if the module
>depends on services or system table fields or PI core behaviors that are not
>present in the PI 1.0 version. For example, if a module depends on definitions
>in PI 1.1 that are not in PI 1.0, then `PI_SPECIFICATION_VERSION` must be
>0x0001000A                                                             |
>+|`UEFI_SPECIFICATION_VERSION`|Not required
>|Decimal or special format of hex| The minimum revision value across the
>module and all its dependent libraries. If a revision value is not declared in the
>module or any of the dependent libraries, then tools may use the value of 0,
>which disables checking.
>|
>+|                            |                                                             |                                | The
>`UEFI_SPECIFICATION_VERSIon` must only be set in the INF file if the module
>depends on UEFI Boot Services or UEFI Runtime Services or UEFI System Table
>fields or UEFI core behaviors that are not present in the UEFI 2.1 version. For
>example, if a module depends on definitions in UEFI 2.2 that are not in UEFI
>2.1, then `UEFI_SPECIFICATION_VERSION` must be 0x00020014         |
>+|`FILE_GUID`                 |REQUIRED                                                     |GUID Value
>| Registry (8-4-4-4-12) Format. This value is required for all EDK II format INF
>files, required for EDK driver INF files, not required for EDK libraries
>|
>+|`MODULE_TYPE`               |REQUIRED                                                     |
>| This is the type of module. One of the EDK II Module Types. For Library
>Modules, the `MODULE_TYPE` must specify the `MODULE_TYPE` of the
>module that will typically use the library.
>|
>+|`BUILD_NUMBER`              |Optional                                                     |UINT16 Value
>| This optional element, if present (or set in the DSC file), is used during the
>creation of the `EFI_VERSION_SECTION` for this module; if it is not present,
>then the BuildNumber field of the `EFI_VERSION_SECTION` will be set to 0.
>|
>+|`VERSION_STRING`            |Optional                                                     |String
>| If present, this value will be encoded as USC-2 characters in a Unicode file
>for the VERSION section of the FFS unless a ver or ver_ui file has been
>specified in the `[Binaries]` section.
>|
>+|`MODULE_UNI_FILE`           |Optional                                                     |Filename
>| A Unicode file containing UCS-2 character localization strings; the file path (if
>present) is relative to the directory containing the INF file. The use of #include
>statements in this file is prohibited.
>|
>+|`LIBRARY_CLASS`             |Typically not specified for Driver; REQUIRED for
>Library only|Word &#124; TypeList            | One Library Class that is satisfied by
>this Library Instance; one or more `LIBRARY_CLASS` lines may be specified by a
>module. The reserved keyword, NULL, must be listed for library class
>instances that do NOT support a library class keyword.
>|
>+|`PCD_IS_DRIVER`             |Not required - Driver Only
>|PEI_PCD_DRIVER or DXE_PCD_DRIVER| Only required for the two
>(PEI_PCD_DRIVER or DXE_PCD_DRIVER) PCD Driver modules.
>|
>+|`ENTRY_POINT`               |Not required - Driver Only                                   |CName
>| This is the name of the driver's entry point function.
>|
>+|`UNLOAD_IMAGE`              |Not required - Driver Only
>|CName                           | If a driver chooses to be unloadable, then this is the
>name of the module's function registered in the Loaded Image Protocol. It is
>called if the UEFI Boot Service UnloadImage() is called for the module, which
>then executes the Unload function, disconnecting itself from handles in the
>database as well as uninstalling any protocols that were installed in the driver
>entry point.|
>+|`CONSTRUCTOR`               |Not required - Library Only
>|CName                           | This only applies to components that are libraries. It is
>required for EDK II libraries if the module's INF contains a Constructor element.
>This value is used to call the specified function before calling into the library
>itself.
>|
>+|`DESTRUCTOR`                |Not required - Library Only                                  |CName
>| This only applies to components that are libraries. This value is used to call
>the specified function before calling into the library itself.
>|
>+|`SHADOW`                    |Not required - SEC, PEIM and PEI_CORE Driver
>modules only    |TRUE &#124; FALSE               | This boolean operator is used by
>`SEC`, `PEI_CORE` and `PEIM` modules to indicate if the module was coded to
>use `REGISTER_FOR_SHADOW`. If the value is TRUE, the .reloc section of the
>PE32 image is not removed, otherwise, the .reloc section is stripped to
>conserve space in the final binary images. The default value is FALSE.
>|
>+|`PCI_DEVICE_ID`             |Not required - Required for UEFI PCI Option ROMs
>|UINT16 Value                    | The PCI Device Id for this device
>|
>+|`PCI_VENDOR_ID`             |Not required - Required for UEFI PCI Option
>ROMs             |UINT16 Value                    | The PCI Vendor Id for this device
>|
>+|`PCI_CLASS_CODE`            |Not required - Required for UEFI PCI Option
>ROMs             |UINT8 Value                     | The PCI Class Code for this device
>|
>+|`PCI_REVISION`              |Not required - Required for UEFI PCI Option ROMs
>|UINT8 Value                     | The PCI revision for this device
>|
>+|`PCI_COMPRESS`              |Not required UEFI PCI Option ROMs
>|TRUE &#124; FALSE               | This flag is used by tools to compress a PCI
>Option ROM image file, the default (if not specified) is FALSE
>|
>+|`UEFI_HII_RESOURCE_SECTION` |Not required - Driver Only
>|TRUE &#124; FALSE               | This boolean operator is used to indicate that
>the module will require a separate HII resource section in the efi image file.
>|
>+|`CUSTOM_MAKEFILE`           |Not required                                                 |Family
>&#124; File              | A user written makefile that will be used, the INF file will
>not be parsed.  The Family is one of MSFT or GCC followed by a field separator
>"&#124;" character, then the filename of the makefile in the same directory as
>the INF file. To keep GCC compatibility, the user must generate two Makefiles,
>one for MSFT, such as makefile and another for GCC, such as GNUmakefile
>|
>+|`SPEC`                      |Not required                                                 |CName = Value
>| A User-specified #define CName Value pair that will be included in the
>`AutoGen.h` file.
>|
>+|`DPX_SOURCE`                |Not Required - Driver Only
>|Filename                        | If present, the file must contain all DEPEX statements
>(as defined in the UEFI PI specification), as the tools will process the file,
>ignoring any content in `[Depex]` sections in this file AND all inherited
>dependencies from libraries. This allows the module owner to force a Depex
>independently. Use of this option is not recommended for normal use.
>|
>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 494b77d..f512ff9 100644
>--- a/3_edk_ii_inf_file_format/34_[defines]_section.md
>+++ b/3_edk_ii_inf_file_format/34_[defines]_section.md
>@@ -141,11 +141,11 @@ recommended.
>                        [<TS> "UEFI_SPECIFICATION_VERSION" <Eq>
>                        <VersionVal> <EOL>]
>                        [<TS> "PI_SPECIFICATION_VERSION" <Eq>
>                        <VersionVal> <EOL>]
>                        [<TS> "LIBRARY_CLASS" <Eq> <LibClass> <EOL>]*
>-                       [<TS> "BUILD_NUMBER" <Eq> <NumValUint16> <EOL>]
>+                       [<TS> "BUILD_NUMBER" <Eq> <UINT16> <EOL>]
>                        [<TS> "VERSION_STRING" <Eq>
>                        <DecimalVersion> <EOL>]
>                        [<TS> "PCD_IS_DRIVER" <Eq>
>                        <PcdDriverType> <EOL>]
>                        [<TS> "ENTRY_POINT" <Eq> <CName> [<FFE>] <EOL>]*
>diff --git a/README.md b/README.md
>index 4cce0a8..813bc1a 100644
>--- a/README.md
>+++ b/README.md
>@@ -198,5 +198,6 @@ Copyright (c) 2007-2017, Intel Corporation. All rights
>reserved.
> |            | [#522](https://bugzilla.tianocore.org/show_bug.cgi?id=522) INF spec:
>add the clarification that PCD value may from build command
>|               |
> | 1.27       | Update version to 1.27
>| Mar 2018      |
> |            | Add Flexible PCD value format support
>|               |
> |            | 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
>|               |
>--
>2.6.1.windows.1