Mike Maslenkin 4811c37ae3 IpmiFeaturePkg: fix IpmiSendCommand response size in GetDeviceId function | 1 year ago | |
---|---|---|
.. | ||
AdvancedFeaturePkg | 1 year ago | |
Debugging | 1 year ago | |
Network | 1 year ago | |
OutOfBandManagement | 1 year ago | |
PlatformPayloadFeaturePkg | 1 year ago | |
PowerManagement | 1 year ago | |
SystemInformation | 1 year ago | |
TemplateFeaturePkg | 1 year ago | |
UserInterface | 1 year ago | |
Readme.md | 2 years ago |
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.
Advanced features should be:
MdePkg
, MdeModulePkg
, UefiCpuPkg
, FmpDevicePkg
, SecurityPkg
, NetworkPkg
, ShellPkg
.MinPlatformPkg
, IntelSiliconPkg
.PcdFeatureEnable
). Any effort to enable the feature
besides this PCD should be carefully considered. Default configuration values should apply to the common case.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.
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:
A single package called AdvancedFeaturePkg
exists with the following responsibilities:
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.
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.
FvAdvancedPreMemory
- Contains advanced feature modules that should be dispatched before permanent memory is enabled.
Typically, these are PEI modules (PEIMs).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.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.
Each feature is maintained in its own feature package called XxxFeaturePkg
where Xxx is replaced by the feature
name.
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:
- A feature package directory (
XxxFeaturePkg
)- A
Readme.md
file in the feature package directory root to describe the feature- Some advanced feature source code (e.g. a PEI or DXE module)
- A feature DSC file (
XxxFeaturePkg/Include/XxxFeature.dsc
)- Feature pre-memory / post-memory FDF files (
XxxFeaturePkg/Include/PreMemory.fdf
&XxxFeaturePkg/Include/PostMemory.fdf
)- A feature package DSC file (
XxxFeaturePkg/XxxFeaturePkg.dsc
)- A feature package DEC file (
XxxFeaturePkg/XxxFeaturePkg.dec
)- A reference in the
AdvancedFeaturePkg
as described in the checklistAdd New Advanced Feature Checklist
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.
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.
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.Use the package template provided by
TemplateFeaturePkg
to create a new advanced feature package in the feature location.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.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.
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.Update the feature FDF include files. These files are
XxxFeaturePkg/Include/PreMemory.fdf
andXxxFeaturePkg/Include/PostMemory.fdf
.
- Each file should contain the feature pre-memory modules and post-memory modules respectively.
Build the advanced feature package to ensure the build is successful: From the workspace root:
- Verify the «WORKSPACE» environment variable is set to the parent of edk2 and edk2-platforms directory in your workspace.
- 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
- cd edk2
- Execute edksetup.bat (Windows) or edksetup.sh (Linux).
- cd edk2-platforms/Features/Intel
build -a IA32 -a X64 -p FeatureDomainDirectory/XxxFeaturePkg/XxxFeaturePkg.dscNote: -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.Add the advanced feature to
AdvancedFeaturePkg
so it is available to board packages.
- Add
XxxFeaturePkg/Include/XxxFeature.dsc
toAdvancedFeatures.dsc
- Add
XxxFeaturePkg/Include/PreMemory.fdf
toAdvancedFeaturePkg/Include/PreMemory.fdf
- Add
XxxFeaturePkg/Include/PostMemory.fdf
toAdvancedFeaturePkg/Include/PostMemory.fdf
- Add the
PcdFeatureEnable
toAdvancedFeaturesPcd.dsc
set to FALSE- Add the
PcdFeatureEnable
toAdvancedFeaturePkg.dsc
set to TRUEBuild
AdvancedFeaturePkg
to ensure the build is successful.
- Follow the steps in step #9 but change the build command to:
build -a IA32 -a X64 -p AdvancedFeaturePkg/AdvancedFeaturePkg.dscBefore sending your patch series, ensure the
Readme.md
file inXxxFeaturePkg
is completed so others can use it during the feature review.