Mike Maslenkin 4811c37ae3 IpmiFeaturePkg: fix IpmiSendCommand response size in GetDeviceId function 1 year ago
..
AdvancedFeaturePkg ab4ddecb12 AdvancedFeaturePkg: Improve sample build instructions 1 year ago
Debugging c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
Network c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
OutOfBandManagement 4811c37ae3 IpmiFeaturePkg: fix IpmiSendCommand response size in GetDeviceId function 1 year ago
PlatformPayloadFeaturePkg d7466862b7 PlatformPayloadFeaturePkg.py: Add Linux support 1 year ago
PowerManagement c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
SystemInformation c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
TemplateFeaturePkg c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
UserInterface c227f900f5 Features/Intel: Prepare for edk2-platforms CI 1 year ago
Readme.md 388975530e AdvancedFeaturePkg: Add missing features 2 years ago

Readme.md

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. A brief overview is also provided in the 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 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 can only depend on following packages:
    • edk2 repo: MdePkg, MdeModulePkg, UefiCpuPkg, FmpDevicePkg, SecurityPkg, NetworkPkg, ShellPkg.
    • edk2-platforms repo: MinPlatformPkg, IntelSiliconPkg.
  • 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.
  • XxxFeaturePkg - A specific feature package described further in 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. 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. 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 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

  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/<Xxx>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 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 include file. This file is in XxxFeaturePkg/Include/XxxFeature.dsc.

    • In most cases, XxxFeaturePkg/XxxFeaturePkg.dsc should just !include XxxFeaturePkg/Include/XxxFeature.dsc.
    • This file should not duplicate core content from MinPlatformPkg/Include/Dsc except where a change is required by the feature.
  8. Update the feature FDF include 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. Verify the «WORKSPACE» environment variable is set to the parent of edk2 and edk2-platforms directory in your workspace.
    2. Set the «PACKAGES_PATH» environment variable to include the edk2, edk2-platforms/Platform/Intel, edk2-platforms/Silicon/Intel, and edk2-platforms/Features/Intel directories.
      • Windows example:
        • set PACKAGES_PATH=%WORKSPACE%\edk2; %WORKSPACE%\edk2-platforms\Platform\Intel; %WORKSPACE%\edk2-platforms\Silicon\Intel; %WORKSPACE%\edk2-platforms\Features\Intel; %WORKSPACE%\edk2-platforms\Features\Intel\Debugging; %WORKSPACE%\edk2-platforms\Features\Intel\Network; %WORKSPACE%\edk2-platforms\Features\Intel\OutOfBandManagement; %WORKSPACE%\edk2-platforms\Features\Intel\PowerManagement; %WORKSPACE%\edk2-platforms\Features\Intel\SystemInformation; %WORKSPACE%\edk2-platforms\Features\Intel\UserInterface
      • Linux example:
        • export PACKAGES_PATH=~Edk2Workspace/edk2: ~/Edk2Workspace/edk2-platforms/Platform/Intel: ~/Edk2Workspace/edk2-platforms/Silicon/Intel: ~/Edk2Workspace/edk2-platforms/Features/Intel: ~/Edk2Workspace/edk2-platforms/Features/Intel/Debugging: ~/Edk2Workspace/edk2-platforms/Features/Intel/Network: ~/Edk2Workspace/edk2-platforms/Features/Intel/OutOfBandManagement: ~/Edk2Workspace/edk2-platforms/Features/Intel/PowerManagement: ~/Edk2Workspace/edk2-platforms/Features/Intel/SystemInformation: ~/Edk2Workspace/edk2-platforms/Features/Intel/UserInterface
    3. cd edk2
    4. Execute edksetup.bat (Windows) or edksetup.sh (Linux).
    5. cd edk2-platforms/Features/Intel
    6. build -a IA32 -a X64 -p FeatureDomainDirectory/XxxFeaturePkg/XxxFeaturePkg.dsc
      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
    4. Add the PcdFeatureEnable to AdvancedFeaturesPcd.dsc set to FALSE
    5. Add the PcdFeatureEnable to AdvancedFeaturePkg.dsc set to TRUE
  11. Build AdvancedFeaturePkg to ensure the build is successful.

    1. Follow the steps in step #9 but change the build command to:
    build  -a IA32 -a X64 -p AdvancedFeaturePkg/AdvancedFeaturePkg.dsc
  12. Before sending your patch series, ensure the Readme.md file in XxxFeaturePkg is completed so others can use it during the feature review.