From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mga05.intel.com (mga05.intel.com []) by mx.groups.io with SMTP id smtpd.web09.933.1574903199589090118 for ; Wed, 27 Nov 2019 17:06:40 -0800 Authentication-Results: mx.groups.io; dkim=missing; spf=fail (domain: intel.com, ip: , mailfrom: michael.a.kubacki@intel.com) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga105.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 27 Nov 2019 17:06:39 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,251,1571727600"; d="scan'208";a="383667591" Received: from makuback-desk1.amr.corp.intel.com ([10.7.159.162]) by orsmga005.jf.intel.com with ESMTP; 27 Nov 2019 17:06:39 -0800 From: "Kubacki, Michael A" To: devel@edk2.groups.io Cc: Dandan Bi , Sai Chaganty , Chasel Chiu , Wei David Y , Nate DeSimone , Eric Dong , Liming Gao , Agyeman Prince Subject: [edk2-platforms][PATCH V2 04/47] Features/Intel: Add Readme.md Date: Wed, 27 Nov 2019 17:05:31 -0800 Message-Id: <20191128010614.43628-5-michael.a.kubacki@intel.com> X-Mailer: git-send-email 2.16.2.windows.1 In-Reply-To: <20191128010614.43628-1-michael.a.kubacki@intel.com> References: <20191128010614.43628-1-michael.a.kubacki@intel.com> This change adds the initial Readme.md to the root of the Features/ Intel directory. The features are maintained in an Intel directory because they are not tested on other systems. If there is interest to support a feature on systems other than Intel, the feature should be tested on those other systems and the feature can be promoted above the Intel directory. This Readme.md is the most important file in the Features/Intel tree as it provides the desired attributes and definition of advanced features, the advanced feature source layout, and the new feature creation checklist. This is the primary documentation file for new users to understand advanced features. Cc: Dandan Bi Cc: Sai Chaganty Cc: Chasel Chiu Cc: Wei David Y Cc: Nate DeSimone Cc: Eric Dong Cc: Liming Gao Cc: Agyeman Prince Signed-off-by: Michael Kubacki --- Features/Intel/Readme.md | 236 ++++++++++++++++++++ 1 file changed, 236 insertions(+) diff --git a/Features/Intel/Readme.md b/Features/Intel/Readme.md new file mode 100644 index 0000000000..9729f90a41 --- /dev/null +++ b/Features/Intel/Readme.md @@ -0,0 +1,236 @@ +# **EDK II Minimum Platform Firmware Advanced Features for Intel® Platforms** + +In the EDK II Minimum Platform, advanced features are non-essential features. Essential features are those required +to achieve an earlier boot stage (Stage I through Stage V). The Minimum Platform boot stages are defined in the +[EDK II Minimum Platform Draft Specification](https://edk2-docs.gitbooks.io/edk-ii-minimum-platform-specification/). A +brief overview is also provided in the [Platform/Intel/Readme.md](https://github.com/tianocore/edk2-platforms/blob/master/Platform/Intel/Readme.md). + +An advanced feature must be implemented as highly cohesive and stand-alone software to only support a specific +feature. Advanced features are the primary method to extend platform firmware capabilities in a modular fashion. + +If you would like to quickly get started creating a new advanced feature, you can jump ahead to the +[Add New Advanced Feature Checklist](#Add-New-Advanced-Feature-Checklist) and reference other sections of this +document as needed. + +## Overview + +### Advanced Feature Attributes +Advanced features should be: +* _Cohesive_, the feature should not contain any functionality unrelated to the feature. +* _Complete_, the feature must have a complete design that minimizes dependencies. A feature package cannot directly + depend on another feature package. +* _Easy to Integrate_, the feature should expose well-defined software interfaces to use and configure the feature. + * It should also present a set of simple and well-documented standard EDK II configuration options such as PCDs to + configure the feature. + * In general, features should be self-contained and started by the dispatcher. The board firmware should + be required to perform as few steps as possible to enable the feature. + * All features are required to have a feature enable PCD (`PcdFeatureEnable`). Any effort to enable the feature + besides this PCD should be carefully considered. Default configuration values should apply to the common case. +* _Portable_, the feature is not allowed to depend on other advanced feature or board source code packages. For example, + if Feature A depends on output Feature B, a board integration module should use a generic interface in Feature A + to get the output and pass it to a generic interface in Feature B. Structures should not be shared between feature + packages. Most structures should be defined in a common package such as MdePkg if the structure is industry standard, + IntelSiliconPkg if the structure is specific to Intel silicon initialization, etc. Feature-specific structures are + of course allowed to be defined within a feature package and used by libraries and modules in that package. +* _Self Documenting_, the feature should follow software best practices to allow others to debug the code and + contribute changes. In addition to source code, advanced features must have a Readme.md with sufficient + information for a newcomer to understand the feature. +* _Single Instance_, the feature should not have more than one instance of a source solution. If an existing feature + package does not solve a specific instance of a problem for the feature, the feature package should be re-worked + to consider new requirements instead of duplicating feature code. + + Features should be written for a specific feature technology. Outside of technology restrictions, the feature + should not make arbitrary assumptions about the type of board or system that may integrate the feature. Any + board or hardware-specific details that may vary in design should be given to the feature through a defined + and documented software interface. + +### Advanced Feature Packages +Feature portability is a key aspect of board scalability. To maintain high cohesion within a feature package and +reduce potential coupling between features, each feature is maintained in a dedicated package. Such encapsulation enables +increased flexibility in implementation, rapid integration with board firmware, improved software maintenance by reducing +coupling between features, and a better scope for feature-focused maintenance and testing over time. + +Two package types exist for advanced features: + * AdvancedFeaturePkg - A special package described further in [AdvancedFeaturePkg](#AdvancedFeaturePkg). + * XxxFeaturePkg - A specific feature package described further in [XxxFeaturePkg](#XxxFeaturePkg). + +#### AdvancedFeaturePkg +A single package called `AdvancedFeaturePkg` exists with the following responsibilities: +1. Present a consolidated and simplified view of all available advanced features to board packages. +2. Provide a single package build for all available advanced features. + 2.a. This can save time. Each feature package will send build output to a package-specific build output directory. + By building a features from a single package build object files can be reused across features. + +##### Template Resources +A template for a new advanced feature package is provided in `TemplateFeaturePkg`. It is recommended to start +a new advanced feature package using this template. The minimally required set of files for an advanced feature to +be acceptable is defined in [Advanced Feature Collateral](#Advanced-Feature-Collateral). Apart from required files, +the content organization within the files should follow the layout provided in the template files. + +##### Consolidated View of All Advanced Features to Board Packages +A board package may consume any number of advanced features. In order to reduce the overall effort required to add +advanced features, all available advanced features are consolidated into single includable files in `AdvancedFeaturePkg`. + +_DSC File_ + +All advanced features are importable to a board package DSC file by simply including `AdvancedFeatures.dsc`. +`AdvancedFeatures.dsc` already includes the conditional logic to only include features that are enabled by the board package. + +_FDF File_ + +The EDK II Minimum Platform has two firmware volumes to contain advanced features. + +1. `FvAdvancedPreMemory` - Contains advanced feature modules that should be dispatched before permanent memory is enabled. + Typically, these are PEI modules (PEIMs). +2. `FvAdvanced` - Contains advanced feature modules that do not need to be executed prior to permanent memory being + initialized. Typically, these are post-memory PEIMs or DXE modules. + +##### Single Build of All Advanced Features +With many advanced feature packages, it is convenient to have a single build target that can build all advanced features. +The `AdvancedFeaturePkg.dsc` enables all the advanced features for its package build. + +#### XxxFeaturePkg +Each feature is maintained in its own feature package called `XxxFeaturePkg` where *Xxx* is replaced by the feature +name. + +### Source Code Organization of Advanced Features +All advanced feature code is maintained in `edk2-platforms/Features`. Features that are only tested on Intel systems +are maintained in `edk2-platforms/Features/Intel`. These features are not intended to be constrained to Intel systems. + +A package resides at the root of `edk2-platforms/Features/Intel` called [AdvancedFeaturePkg](#AdvancedFeaturePkg). +All feature packages are organized into directories by feature domain. Each feature domain directory is required to +have a `Readme.md` that explains the scope of features for that domain. Each feature package is required to have a +`Readme.md` that explain the feature. All feature packages are required to base their `Readme.md` on the +[template](TemplateFeaturePkg/Readme.md) provided in `TemplateFeaturePkg`. + +A generic tree layout of the advanced features is illustrated below. The contents are shown at the time of writing but +of course, are subject to change over time. + + 
+    WORKSPACE
+          |------edk2
+          |------edk2-non-osi
+          |------edk2-platforms
+          |       |---Features
+          |       |    |--Intel
+          |       |        |------AdvancedFeaturePkg
+          |       |        |
+          |       |        |------TemplateFeaturePkg
+          |       |        |
+          |       |        |------Debugging: Debug related advanced features
+          |       |        |       |------AcpiDebugFeaturePkg
+          |       |        |       |       |---AcpiDebugDxeSmm (module directories)
+          |       |        |       |       |---.  .  .
+          |       |        |       |       |---Include
+          |       |        |       |       |    |---AcpiDebugFeature.dsc (feature build DSC file)
+          |       |        |       |       |    |---PostMemory.fdf (post-memory feature modules)
+          |       |        |       |       |    |---PreMemory.fdf (pre-memory feature modules)
+          |       |        |       |       |    |---.  .  .
+          |       |        |       |       |---AcpiDebugFeaturePkg.dec (feature package DEC file)
+          |       |        |       |       |---AcpiDebugFeature.dsc (feature package build DSC file)
+          |       |        |       |
+          |       |        |       |------Usb3DebugFeaturePkg
+          |       |        |       |       |---.  .  .
+          |       |        |       |
+          |       |        |       |------.  .  .
+          |       |        |------Network: Network related advanced features
+          |       |        |       |------.  .  .
+          |       |        |
+          |       |        |------OutOfBandManagement: Out-of-Band Management related advanced features
+          |       |        |       |------.  .  .
+          |       |        |
+          |       |        |------PowerManagement: Power Management related advanced features
+          |       |        |       |------.  .  .
+          |       |        |
+          |       |        |------SystemInformation: System Information related advanced features
+          |       |        |       |------.  .  .
+          |       |        |
+          |       |        |------UserInterface: User Interface related advanced features
+          |       |        |       |------.  .  .
+          |       |        |
+          |------FSP
+
+ +## Adding a New Advanced Feature + +### Advanced Feature Collateral +At a minimum, an advanced feature must consist of the following elements: +1. A feature package directory (`XxxFeaturePkg`) +2. A `Readme.md` file in the feature package directory root to describe the feature +3. Some advanced feature source code (e.g. a PEI or DXE module) +4. A feature DSC file (`XxxFeaturePkg/Include/XxxFeature.dsc`) +5. Feature pre-memory / post-memory FDF files (`XxxFeaturePkg/Include/PreMemory.fdf` & `XxxFeaturePkg/Include/PostMemory.fdf`) +6. A feature package DSC file (`XxxFeaturePkg/XxxFeaturePkg.dsc`) +7. A feature package DEC file (`XxxFeaturePkg/XxxFeaturePkg.dec`) +8. A reference in the `AdvancedFeaturePkg` as described in the [checklist](#Add-New-Advanced-Feature-Checklist) + +### Add New Advanced Feature Checklist +1. Check if a feature package already exists for your new feature. + * If it does, use the existing feature package. If changes are needed to meet your requirements, work with the + package maintainer to make any required updates to the existing package. + +2. Determine the functional domain of your feature. For example, "Debugging", "Power Management", etc. This should not be + very specific and abstracted so the feature is available alongside similar feature packages for the given domain. It + is preferred to keep the number of feature domain directories minimal but new directories can be created if needed. + +3. Decide on a succinct name for your feature package. + * The name should be descriptive enough to uniquely identify the feature from similar features in the same feature + domain. + + * At this point, the feature package location is: `FeatureDomain/FeaturePkg`. + + * For example, the ACPI Debug feature is located in `Debugging/AcpiDebugFeaturePkg` based on this naming pattern. + +4. Use the package template provided by `TemplateFeaturePkg` to create a new advanced feature package in the + feature location. + +5. Review the [advanced feature attributes](#Advanced-Feature-Attributes) to draft a feature design proposal. + * It is recommended to use the template in `TemplateFeaturePkg/Readme.md` to document the feature design for review. + Once the design review is approved, a subsequent review can be sent for the feature implementation. An advantage to + this approach is that the requirement to complete a Readme.md file for the feature and gain approval in a feature + design review are combined into a single step. + +6. Add the source code for the advanced feature. + * If the feature is large it is recommended to add libraries in one patch and then modules in a following patch. + +7. Update the feature DSC file. This file is in `XxxFeaturePkg/Include/XxxFeature.dsc`. + * In most cases, `XxxFeaturePkg/XxxFeaturePkg.dsc` should just `!include XxxFeaturePkg/Include/XxxFeature.dsc`. + +8. Update the feature FDF files. These files are `XxxFeaturePkg/Include/PreMemory.fdf` and + `XxxFeaturePkg/Include/PostMemory.fdf`. + * Each file should contain the feature pre-memory modules and post-memory modules respectively. + +9. Build the advanced feature package to ensure the build is successful: + + From the workspace root: + 1. cd edk2-platforms/edk2 + 2. Execute edksetup.bat (Windows) or edksetup.sh (Linux). + 3. Verify the "WORKSPACE" environment variable is set to the edk2 directory in your workspace. + 4. Set the "PACKAGES_PATH" environment variable to include the edk2-platforms/Platform/Intel, edk2-platforms/Silicon/Intel, + and edk2-platforms/Features/Intel directories. + * Windows example: + * set PACKAGES_PATH=c:\Edk2Workspace\edk2-platforms\Platform\Intel; + c:\Edk2Workspace\edk2-platforms\Silicon\Intel; + c:\Edk2Workspace\edk2-platforms\Features\Intel + * Linux example: + * export PACKAGES_PATH=~/Edk2Workspace/edk2-platforms/Platform/Intel: + ~/Edk2Workspace/edk2-platforms/Silicon/Intel: + ~/Edk2Workspace/edk2-platforms/Features/Intel + 5. cd edk2-platforms/Features/Intel + 6. 
build -p FeatureDomainDirectory/XxxFeaturePkg/XxxFeaturePkg.dsc -a IA32 -a X64
+ + *Note:* -a specifies the architecture. Typically IA32 and X64 modules are built for 32-bit PEI and 64-bit + DXE though build for your specific requirements. + +10. Add the advanced feature to `AdvancedFeaturePkg` so it is available to board packages. + 1. Add `XxxFeaturePkg/Include/XxxFeature.dsc` to `AdvancedFeatures.dsc` + 2. Add `XxxFeaturePkg/Include/PreMemory.fdf` to `AdvancedFeaturePkg/Include/PreMemory.fdf` + 3. Add `XxxFeaturePkg/Include/PostMemory.fdf` to `AdvancedFeaturePkg/Include/PostMemory.fdf` + +11. Build `AdvancedFeaturePkg` to ensure the build is successful. + 1. Follow the steps in step #9 but change the build command to: + + 
build -p AdvancedFeaturePkg/AdvancedFeaturePkg.dsc -a IA32 -a X64
+ +12. Before sending your patch series, ensure the `Readme.md` file in `XxxFeaturePkg` is completed so others can use it + during the feature review. -- 2.16.2.windows.1