As far as where this type documentation can go there are a couple options.
Mike
From: devel@edk2.groups.io <devel@edk2.groups.io>
On Behalf Of Chang, Abner via groups.io
Sent: Monday, September 26, 2022 12:34 AM
To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
Cc: Ni, Ray <ray.ni@intel.com>; Sunil V L <sunilvl@ventanamicro.com>; lichao <lichao@loongson.cn>; Kirkendall, Garrett <Garrett.Kirkendall@amd.com>; Grimes, Paul <Paul.Grimes@amd.com>; He, Jiangang <Jiangang.He@amd.com>; Attar, AbdulLateef (Abdul Lateef)
<AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindhol@quicinc.com>; Andrew Fish <afish@apple.com>
Subject: Re: [edk2-devel] The principles of EDK2 module reconstruction for archs
[AMD Official Use Only - General]
Thanks for the reply Mike,
>>> I think it would be good to clarify when a difference in implementation is due to a CPU Arch difference or a Vendor implementation difference.
Right, we can have a paragraph to clarify the difference of CPU Arch or a vendor implementation of the same CPU Arch.
If the difference of CPU Arch or a vendor implementation triggers the module reconstruction; and it is a new module or the delta is huge to share the same module, then the file/module name should follow the naming rule you listed above.
It the difference could be added to the existing module, then I think we just keep the existing naming of the file/module to prevent from introducing the impacts on the existing platform or projects meta files.
>>>I am not sure if we should use “Common” in the naming conventions. I think by default, any content that is not CpuArch or Vendor specific could be considered common content.
Yes agree. The existing file could be a common file if there is no CpuArch or Vendor tag in the file/module name. However, there would be four scenarios,
Strip away the share code and put it into new file and name it without arch/vendor tag. We don’t need “common” in the file name.
Strip away the arch/vendor specific code and put it into new file named with arch/vendor tag.
Keep it without any change on file/module name.
How is it?
I will revise the doc. I don’t see the good place to create this doc and PR for the review online. I would just create a markdown file under tianocore.github.io/docs just for the temporary. Any other suggestions?
Thanks
Abner
From: Kinney, Michael D <michael.d.kinney@intel.com>
Sent: Saturday, September 24, 2022 2:01 AM
To: devel@edk2.groups.io; Chang, Abner <Abner.Chang@amd.com>; Kinney, Michael D <michael.d.kinney@intel.com>
Cc: Ni, Ray <ray.ni@intel.com>; Sunil V L <sunilvl@ventanamicro.com>; lichao <lichao@loongson.cn>; Kirkendall, Garrett <Garrett.Kirkendall@amd.com>;
Grimes, Paul <Paul.Grimes@amd.com>; He, Jiangang <Jiangang.He@amd.com>; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>;
Leif Lindholm <quic_llindhol@quicinc.com>; Andrew Fish <afish@apple.com>
Subject: RE: The principles of EDK2 module reconstruction for archs
Caution: This message originated from an External Source. Use proper caution when opening attachments, clicking links, or responding.
|
Hi Abner,
I think it would be good to clarify when a difference in implementation is due to a CPU Arch difference or a Vendor implementation difference.
I would also be good to provide guidelines for directory names and file names for all EDK II meta data file types. Here are some examples to get started:
Package Directory Name: <PackageName>Pkg
Package DEC File Name: <PackageName>Pkg.dec
<PackageName> REQUIRED *
Module Directory Name: <ModuleName><Phase>
< Feature >/<Phase>
Module INF File Name: <ModuleName><Phase>.inf
< Feature>/<Phase>/<ModuleName>.inf
<Feature> OPTIONAL Only used if implementation does not have any shared code between phases (e.g. MdeModulePkg/Universal/PCD)
<Phase> REQUIRED Base, Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi
<ModuleName> REQUIRED *
Library Instance Directory Name: <Phase><CpuArch><Vendor><LibraryClassName><Dependency>
Library Instance INF File Name: <Phase><CpuArch><Vendor><LibraryClassName><Dependency>.inf
<Phase> REQUIRED Base, Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm, Uefi
<CpuArch> OPTIONAL Ia32, X64, Arm, AArch64, RiscV64, LoongArch64, Ebc If not provided, then component supports >=2 or all CPU archs
<Vendor> OPTIONAL *
<LibraryClassName> REQUIRED *
<Dependency> OPTIONAL * Typically name of PPI, Protocol, LibraryClass that the implementation is layered on top of.
Source File Paths within a Library/Module instance
<FileName>.c
<FileName>.h
<CpuArch>/<FileName>.c
<CpuArch>/<FileName>.h
<CpuArch>/<FileName>.nasm
<CpuArch>/<FileName>.S
<CpuArch> OPTIONAL Ia32, X64, Arm, AArch64, RiscV64, LoongArch64, Ebc
I think the point you are raising in the discussion is that sometimes there may be shared content between a small subset of CPU archs (e.g. IA32/X64 or Arm/AArch64 or RiscV32/RiscV64/RiscV128) and that you are proposing a new standard directory
name for these combinations. Your proposal is X86 for a directory that contains content for both IA32 and X64. You are also wanting to support vendor specific content in the naming convention. An example where it is already being done is in MdePkg/Include/Registers/<VendorName>.
So an enhancement to the above Source File Paths would be:
Source File Paths within a Library/Module instance
<FileName>.c
<FileName>.h
<CpuArch>/<FileName>.c
<CpuArch>/<FileName>.h
<CpuArch>/<FileName>.nasm
<CpuArch>/<FileName>.S
<CpuArch>/<Vendor>/<FileName>.c
<CpuArch>/<Vendor>/<FileName>.h
<CpuArch>/<Vendor>/<FileName>.nasm
<CpuArch>/<Vendor>/<FileName>.S
<CpuArch> OPTIONAL Ia32, X64, Arm, AArch64, RiscV64, LoongArch64, Ebc,
X86
<Vendor> OPTIONAL *
I am not sure if we should use “Common” in the naming conventions. I think by default, any content that is not CpuArch or Vendor specific could be considered common content.
Thanks,
Mike
From:
devel@edk2.groups.io <devel@edk2.groups.io>
On Behalf Of Chang, Abner via groups.io
Sent: Friday, September 23, 2022 8:39 AM
To: devel@edk2.groups.io
Cc: Ni, Ray <ray.ni@intel.com>; Kinney, Michael D <michael.d.kinney@intel.com>; Sunil V L <sunilvl@ventanamicro.com>;
lichao <lichao@loongson.cn>; Kirkendall, Garrett <Garrett.Kirkendall@amd.com>; Grimes, Paul <Paul.Grimes@amd.com>; He, Jiangang
<Jiangang.He@amd.com>; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>; Leif Lindholm <quic_llindhol@quicinc.com>;
Andrew Fish <afish@apple.com>
Subject: [edk2-devel] The principles of EDK2 module reconstruction for archs
[AMD Official Use Only - General]
All,
Today in edk2 open design meeting, we went through the draft of principles of the EDK2 module reconstruction for accommodating different archs (IA32, X64, Arm, AArch64, RiscV64, Loongson64 and etc.) or different vendors of the same arch
(AMD/Intel to IA32 and X64).
@Ray Ni and
@michael.d.kinney@intel.com
i. Says the maintainer/reviewer owns the package, however the patch is specific to AMD implementation but the change is in the file that mixes up Intel and AMD code. Then
who is supposed the right person to give the reviewed-by? Perhaps the AMD edk2 module maintainers or reviewers is the proper person to give the reviewed-by for this case. Of course, other maintainers still can join the review process and give the comments.
So to separate the arch-specific code in a arch-specific source file simplifies the review, even that is just a small delta between two implementations.
ii. We can have the maintainers or reviewers for the entire module or *Amd* files only. So the maintainers/reviewers do not have to review the changes that only made
for other archs. But they have to help reviewing the common code if that gets impact.
Lets discuss this using PR if possible.
Thanks
Abner
Below is the draft of principles:
Preface:
The principle is mainly for UefiCpuPKg, but the same principle maybe applied to the EDK2 module that has the processor architecture dependence (such as the BaseLib under MdePkg/Library). Most of the EDK2 modules under UefiCpuPkg were developed
specifically to IA32/X64 architecture, that is necessary to reconstruct the folder or revise the source files to accommodate other processor architectures. The EDK2 module reconstruction is also required for accommodating the same-arch-but-different-vendor’s
implementation (e.g., Intel and AMD for the X86 based processors). The EDK2 module may be strictly developed based on the specific processor architecture. The new introduced implementation for other processor architectures may consider to have a separate EDK2
module instance. Not all of the EDK2 modules revising can exactly meet the principles listed below, that depends on the delta between the original EDK2 module and the implementation for the new introduced processor architecture. It may require the further
discussions with EDK2 module maintainers.
The [Arch] refers to the Processor Architecture.
The [Module] refer to the EDK2 module.
The [X86] refers to both IA32 and X64.
The principles to create the X86 folder in the module:
A-1. If the module is obviously used by IA32/X64 only
A-2. If the existing module is expected to accommodate the different archs or the module already has multiple archs:
B-1. The module INF metafile
B-2. Source files
The new arch implementation is introduced to the module in order to leverage the source code and the module design architecture, so
<OriginalFileName ><arch>.*
< OriginalFileNaming >Common.*
B-1. The module INF metafile
B-2. Source files
The new arch implementation is introduced to this module in order to leverage the source code and the module design architecture, so
< OriginalFileNaming ><arch>.*
<OriginalFileNaming>Common.*
Create a separate module instance. The naming of the module should follow below format,
< OriginalModuleNaming><arch>