Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

edk II C Coding Standard: File and directory naming guidelines #2

Closed
wants to merge 2 commits into from
Closed

edk II C Coding Standard: File and directory naming guidelines #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
65bc588
edk II C Coding Standard: Insert Directory Names section
changab Oct 4, 2022
87c8ed9
edk II C Coding Standard: Updates 4.2 and 4.3 sections
changab Oct 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
131 changes: 131 additions & 0 deletions 4_naming_conventions/42_directory_names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
<!--- @file
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
modification, are permitted provided that the following conditions are met:

1) Redistributions of source code (original document form) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2) Redistributions in compiled form (transformed to other DTDs, converted to
PDF, epub, HTML and other formats) must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
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 uniformity of directory naming, but they also provide 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 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 architectures:

```
<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.
```
60 changes: 0 additions & 60 deletions 4_naming_conventions/42_file_names.md
View file
Open in desktop

This file was deleted.

167 changes: 167 additions & 0 deletions 4_naming_conventions/43_file_names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
<!--- @file
4.3 File Names

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
modification, are permitted provided that the following conditions are met:

1) Redistributions of source code (original document form) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2) Redistributions in compiled form (transformed to other DTDs, converted to
PDF, epub, HTML and other formats) must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

-->

## 4.3 File Names

### 4.3.1 There is no limit to file name lengths.

Do not assume that file names must be 8.3 compatible. Be reasonable though. Let
the file names be as long as necessary, but no longer. Some operating systems
limit file names to 32 characters.

### 4.3.2 Spaces in file and directory names are NOT permitted.

Allowing spaces would cause problems with certain versions of existing industry
tools and does not provide additional clarity.

### 4.3.3 Never start file names with numbers.

Most source control systems will not be able to handle file names that start
with numbers.

### 4.3.4 Non-standard characters shall not occur in file names.

All file names within an EDK II source tree must comply with the following
regular expression:

```
[A-Za-z][_A-Za-z0-9-]*[A-Za-z0-9]+
```

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.3.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: Ia32X64Arm 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd better not define the rule for source files. Let's give freedom to developers. :)
Any change to the source file names only impacts the INF content.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FileName gives the freedom to developers when there is no <CpuArch> and <Vendor>, however, we should define the rules when considering the archs and vendors in the source file name. But I can remove the second part because it mixes up the file and directory naming.


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 Refer to 4.3.1 to 4.3.4 sections for the file
naming format.

Example:
SmmCpuFeatureLib.c
SmmCpuFeatureLibCommon.c
Ia32X64SmmCpuFeaturesLib.c
Ia32X64IntelSmmCpuFeaturesLib.c
AmdSmmCpuFeaturesLib.c

```