public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
* [tianocore-docs][PATCH V2 2/2] edk II C Coding Standard: Updates 4.2 and 4.3 sections
@ 2022-10-15 11:47 Chang, Abner
  2022-10-18  6:01 ` [edk2-devel] " Ni, Ray
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Chang, Abner @ 2022-10-15 11:47 UTC (permalink / raw)
  To: devel
  Cc: Ray Ni, Michael D Kinney, Sunil V L, Abdul Lateef Attar,
	Leif Lindholm

From: Abner Chang <abner.chang@amd.com>

Updates 4.2 Directory names and 4.3 file names for
the guidelines of module directory and file naming.

PR: https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/pull/2/files

Signed-off-by: Abner Chang <abner.chang@amd.com>
Cc: Ray Ni <ray.ni@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Sunil V L <sunilvl@ventanamicro.com>
Cc: Abdul Lateef Attar <abdattar@amd.com>
Cc: Leif Lindholm <quic_llindhol@quicinc.com>
---
 4_naming_conventions/42_directory_names.md | 101 +++++++++++++++++++
 4_naming_conventions/43_file_names.md      | 108 ++++++++++++++++++++-
 2 files changed, 208 insertions(+), 1 deletion(-)

diff --git a/4_naming_conventions/42_directory_names.md b/4_naming_conventions/42_directory_names.md
index 766ccb1..959a3c9 100644
--- a/4_naming_conventions/42_directory_names.md
+++ b/4_naming_conventions/42_directory_names.md
@@ -2,6 +2,7 @@
   4.2 Directory Names
 
   Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved.<BR>
+  Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
@@ -28,3 +29,103 @@
   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 -->
+
+## 4.2 Directory Names
+Below sections are the directory naming guidelines for EDK II modules. The guidelines are not
+just considering the the uniformity of directory naming, but it also provides the flexibility of
+directory name construction for the scenario of different EDK II module designs; such as the
+support for multiple processor architectures and vendors. It may require the further discussions
+between EDK II maintainers and contributors in order to determine the best naming of the EDK II
+module directory.
+
+#### 4.2.1 EDKII package directory
+
+```
+<PackageName>Pkg
+
+   <PackageName> REQUIRED  *
+```
+
+#### 4.2.2 EDKII Module directory
+
+* The guideline below is applied to all CPU architectures support, specific CPU architecture and vendors support, or the implementation is shared by certain CPU archs:
+```
+<Feature><Phase>[<CpuArch>[<Vendor>]]
+  or
+<Feature><Phase>[/<CpuArch>[/<Vendor>]]
+
+   <Feature>      REQUIRED    *
+   <Phase>        REQUIRED    Base, Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm,
+                              Uefi.
+   <CpuArch>      OPTIONAL    The <CpuArch> is represented with a BNF,
+                              <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                        'LoongArch64' | 'Ebc'   
+                              <CpuArch> ::= <arch>[<arch>]*
+                              
+                              Example: Ia32X64Arm or RiscV64LoongArch64
+                              
+   <Vendor>       OPTIONAL    *
+
+Example:
+   - SmbiosDxe/
+   - CpuDxe/                    # First implementation of CpuDxe.
+   - CpuDxeIa32X64Amd/          # Ia32 and X64 AMD specific implementation.
+   - CpuDxe/RiscV64/            # RiscV64 specific implementation.
+           /                    # Common files for the RiscV64 and other archs.
+   - CpuDxe/Ia32X64/Amd/        # Ia32 and X64 AMD specific implementation.
+                   /            # Common files for Ia32 and X64 archs.
+           /ArmAArch64/         # Arm and AArch64 implementation of CpuDxe.
+           /                    # Common files for the Arm, AArch64, Ia32 and X64.
+```
+
+* If the implementation does not have any shared code between phases (e.g.
+MdeModulePkg/Universal/PCD). The guideline below is applied to all CPU architectures support, specific CPU architecture and vendors support, or the implementation is shared by certain CPU archs:
+
+```
+<Feature>/<Phase>[/<CpuArch>[/<Vendor>]]
+
+   <Feature>      REQUIRED    *
+   <Phase>        REQUIRED    Base, Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm, Smm,
+                              Uefi.
+   <CpuArch>      OPTIONAL    The <CpuArch> is represented with a BNF,
+                              <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                        'LoongArch64' | 'Ebc'
+                              <CpuArch> ::= <arch>[<arch>]*
+
+                              Example: Ia32X64Arm or RiscV64LoongArch64
+   <Vendor>       OPTIONAL    *
+Example:
+   Pcd/Dxe/
+```
+
+#### 4.2.2 EDKII Library directory
+```
+<Phase>[<CpuArch>[<Vendor>]]<LibraryClassName>[<Dependency>]
+  or
+<Phase><LibraryClassName>[<Dependency>]/[<CpuArch>[/<Vendor>]]
+
+   <Phase>              REQUIRED     Base, Sec, Pei, Dxe, DxeRuntime, Mm,
+                                     StandaloneMm, Smm, Uefi.
+   <CpuArch>            OPTIONAL     The <CpuArch> is represented with a BNF,
+                                     <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                               'LoongArch64' | 'Ebc'
+                                     <CpuArch> ::= <arch>[<arch>]*
+
+                                     Example: Ia32X64Arm or RiscV64LoongArch64
+   <Vendor>             OPTIONAL     *
+   <LibraryClassName>   REQUIRED     *
+   <Dependency>         OPTIONAL     * (Typically name of PPI, Protocol, LibraryClass
+                                       that the implementation is layered on top of).
+
+Example:
+   - BaseXApicLib/
+   - SmmIa32X64AmdSmmCpuFeaturesLib/
+   - SmmArmAArch64SmmCpuFeaturesLib/
+   - BaseMpInitLib/RiscV64/        # RiscV64 specific implementation.
+                  /Ia32X64/        # Ia32 and X64 specific implementation.
+                  /Ia32X64/Amd     # Ia32 and X64 AMD specific implementation.
+                  /ArmAArch64/     # Arm and AAch64 specific implementation.
+                  /LoongArch64/    # LoongArch64 specific implementation.
+                  /                # Common files for RiscV64, Ia32, X64, Arm, AArch64 and
+                                   LoongArch64.
+```
diff --git a/4_naming_conventions/43_file_names.md b/4_naming_conventions/43_file_names.md
index 13e0c63..5714008 100644
--- a/4_naming_conventions/43_file_names.md
+++ b/4_naming_conventions/43_file_names.md
@@ -1,7 +1,8 @@
 <!--- @file
   4.3 File Names
 
-  Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2006-2022, Intel Corporation. All rights reserved.<BR>
+  Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
@@ -58,3 +59,108 @@ regular expression:
 
 That is, a letter followed by zero, or more, letters, underscores, dashes, or
 digits followed by a period followed by one or more letters or digits.
+
+### 4.3.5 File naming guidelines for modules
+
+Below sections are the file naming guidelines for EDK II meta files and source files. The
+guidelines are not just considering the the uniformity of file naming, but it also provides
+the flexibility of file name construction for the scenario of different EDK II module
+designs; such as the support for multiple processor architectures and vendors. It may require the
+further discussions between EDK II maintainers and contributors in order to determine the best
+naming of the EDK II module file.
+
+#### 4.3.5.1 EDK II meta files within a package
+
+```
+<PackageName>Pkg.dec
+<PackageName>Pkg.dsc
+
+   <PackageName> REQUIRED  *
+```
+
+#### 4.3.5.2 EDK II INF file within a Module instance
+* If the implementation is for all CPU architectures, specific CPU architectures, CPU vendors or the implementation is shared by certain CPU archs:
+```
+<Feature><Phase>[<CpuArch>][<Vendor>].inf
+
+   <Feature>      REQUIRED    *
+   <Phase>        REQUIRED    Base, Sec, Pei, Dxe, DxeRuntime, Mm, StandaloneMm,
+                              Smm, Uefi.
+   <CpuArch>      OPTIONAL    The <CpuArch> is represented with a BNF,
+                              <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                        'LoongArch64' | 'Ebc'
+                              <CpuArch> ::= <arch>[<arch>]*
+                              
+                              Example: Ia32X64Arm or RiscV64LoongArch64
+   <Vendor>       OPTIONAL    *
+
+Example:
+   - SmbiosDxe.inf
+   - CpuIo2Dxe.inf
+   - CpuIo2DxeAmd.inf
+   - CpuIo2DxeIa32X64.inf
+   - CpuIo2DxeIa32X64Intel.inf
+```
+
+* If the implementation does not have any shared code between phases (e.g., Pcd/Dxe):
+
+```
+[<Feature>][<CpuArch>][<Vendor>].inf
+
+   <Feature>      OPTIONAL    *
+   <CpuArch>      OPTIONAL    The <CpuArch> is represented with a BNF,
+                              <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                        'LoongArch64' | 'Ebc'
+                              <CpuArch> ::= <arch>[<arch>]*
+                              
+                              Example: Ia32X64Arm or RiscV64LoongArch64
+   <Vendor>       OPTIONAL    *
+Example:
+   Pcd.inf
+```
+
+#### 4.4.5.3 EDK II INF file within a Library instance
+```
+<Phase>[<CpuArch>][<Vendor>]<LibraryClassName>[<Dependency>].inf
+   <Phase>              REQUIRED     Base, Sec, Pei, Dxe, DxeRuntime, Mm,
+                                     StandaloneMm, Smm, Uefi.
+   <CpuArch>            OPTIONAL     The <CpuArch> is represented with a BNF,
+                                     <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                               'LoongArch64' | 'Ebc'
+                                     <CpuArch> ::= <arch>[<arch>]*
+                              
+                                     Example: Ia32X64_Arm or RiscV64LoongArch64
+   <Vendor>             OPTIONAL     *
+   <LibraryClassName>   REQUIRED     *
+   <Dependency>         OPTIONAL     * (Typically name of PPI, Protocol, LibraryClass
+                                       that the implementation is layered on top of)
+
+Example:
+   - SmmAmdSmmCpuFeaturesLib.inf
+   - SmmIa32X64SmmCpuFeaturesLib.inf
+```
+
+#### 4.3.5.4 EDK II source files within a Library/Module instance
+
+In generally, the file name is constructed as below:
+```
+
+[<CpuArch>][<Vendor>]<FileName>.*
+
+   <CpuArch>   OPTIONAL   The <CpuArch> is represented with a BNF,
+                          <arch> ::='Ia32' | 'X64' | 'Arm' | 'AArch64' | 'RiscV64' |
+                                    'LoongArch64' | 'Ebc'
+                          <CpuArch> ::= <arch>[<arch>]*
+
+                          Example: Ia32X64Arm or RiscV64LoongArch64
+   <Vendor>    OPTIONAL   *
+   <FileName>  REQUIRED   *
+
+Example:
+   SmmCpuFeatureLib.c
+   SmmCpuFeatureLibCommon.c
+   Ia32X64SmmCpuFeaturesLib.c
+   Ia32X64IntelSmmCpuFeaturesLib.c
+   AmdSmmCpuFeaturesLib.c
+
+```
\ No newline at end of file
-- 
2.37.1.windows.1


^ permalink raw reply related	[flat|nested] 9+ messages in thread
end of thread, other threads:[~2022-10-19  4:17 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-10-15 11:47 [tianocore-docs][PATCH V2 2/2] edk II C Coding Standard: Updates 4.2 and 4.3 sections Chang, Abner
2022-10-18  6:01 ` [edk2-devel] " Ni, Ray
2022-10-18  9:50   ` Chang, Abner
2022-10-19  1:31     ` Chang, Abner
2022-10-19  3:34     ` Ni, Ray
2022-10-19  4:17       ` Chang, Abner
2022-10-18 13:33 ` Sunil V L
2022-10-18 15:23   ` Chang, Abner
2022-10-19  2:24 ` Attar, AbdulLateef (Abdul Lateef)

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox