Skip to content

Commit 8732d63

Browse files
lgao4lgao4
committed
EDKII ModuleWriteGuide: Add the converted gitbook
Its PDF is from below link https://github.com/tianocore-docs/Docs/raw/master/User_Docs/EDK_II%20Module%20Writer_s%20Guide_0_7.pdf Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Dongao Guo <[email protected]> Signed-off-by: Liming Gao <[email protected]>
1 parent 106d230 commit 8732d63

File tree

80 files changed

+6866
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+6866
-1
lines changed

Diff for: ‎.gitignore

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Node rules:
2+
## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
3+
.grunt
4+
5+
## Dependency directory
6+
## Commenting this out is preferred by some people, see
7+
## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git
8+
node_modules
9+
10+
# Book build output
11+
_book
12+
13+
# eBook build output
14+
*.epub
15+
*.mobi
16+
*.pdf

Diff for: ‎1_the_basics_of_edk_ii/11_overview.md

+242
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
<!--- @file
2+
1.1 Overview
3+
4+
Copyright (c) 2010-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 1.1 Overview
33+
34+
This chapter also clarifies new concepts introduced with EDK II.
35+
36+
Reference the _EDK II User Manual_, to understand how to obtain EDK II and how
37+
to build existing modules.
38+
39+
### 1.1.1 Module, Package and Platform
40+
41+
#### 1.1.1.1 What is a Module?
42+
43+
A module is the smallest piece of separately compile-able code or pre-built
44+
binary. It contains a metadata file (INF) plus source code or binary. The INF
45+
file is required by the EDKII build system to describe a module's behavior,
46+
such as produced or consumed library classes, ppis, guids, protocols, pcds, and
47+
other information.
48+
49+
For example, in $WORKSPACE\MdeModulePkg\Universal\Bus\Pci\UhciDxe, the source
50+
files mentioned and the INF file compose a module.
51+
52+
,Refer to the _EDK II Extended INF Specification_. for the syntax of the INF
53+
file.
54+
55+
#### 1.1.1.2 What is a Package?
56+
57+
A package is a group of zero or more modules. A package must contain a package
58+
metadata file (DEC), and possibly a platform metadata file (DSC).
59+
60+
Functionally, a package is a logical division of a project. Developers depend
61+
on reasonable judgment, such as license or specification compliance, to
62+
determine where to place a module. These metadata files and the module's INF
63+
files are used by the EDK II build system to automatically generate makefiles
64+
and a single module tip or whole flash tip, according to the build options used.
65+
66+
For information regarding the syntax of DSC and DEC files, please refer to _EDK
67+
II DSC File Specification_ and _EDK II DEC File Specification_.
68+
69+
#### 1.1.1.3 What is a Platform?
70+
71+
A platform is a special type of package with additional metadata files. A
72+
package must contain one DSC file and zero or one FDF file. The FDF is only
73+
required if flash output is required.
74+
75+
Refer to _EDK II FDF File Specification_ for information regarding FDF files..
76+
77+
Refer to the _EDK II Platform Port Guide_ for information about platform
78+
porting between EDK and EDK II.
79+
80+
### 1.1.2 Module Customization
81+
82+
Use the _EDK II User Manual_ to understand the design purpose of the Library
83+
class/Library instance and PCD mechanisms. These mechanisms provide ways for
84+
developers to customize modules without changing the source code.
85+
86+
#### 1.1.2.1 Library class/Library instance
87+
88+
Developers may choose a proper library instance according to its requirements,
89+
such as from performance, image size, or the limitation of module type.
90+
91+
In $WORKSPACE\MdePkg core package, there are many supported library classes and
92+
corresponding library instances. Browse the $WORKSPACE\MdePkg \include\library
93+
directory for basic information regarding the helper function API provided by
94+
these library classes.
95+
96+
#### 1.1.2.2 PCD
97+
98+
Developers may take advantage of the PCD mechanism to extract information from
99+
outside a module, and control procedure behavior inside a module. The
100+
information may be known at compile time from the platform DSC or the package
101+
DEC files, but some files may arrive at flash image generation time, and some
102+
may be determined during execution.
103+
104+
Example:, in the following chapter, `PcdDebugPropertyMask` declared in
105+
MdePkg.dec file in $WORKSPACE\MdePkg is used to control DebugLib behavior. This
106+
PCD is FixedAtBuild type, meaning its value is determined at build time. The
107+
EDK II build system converts this pcd to the value configured in DEC or DSC to
108+
enable or disable the print ability.
109+
110+
### 1.1.3 EDK II Development Lifecycle
111+
112+
The lifecycle of EDK II development is divided into the five phases which
113+
follow.
114+
115+
#### 1.1.3.1 Phase 1: Create a package
116+
117+
A package is the container of modules. A developer should first consider where
118+
the module should be placed. As a general rule, modules newly developed by an
119+
IHV/IBV should not be placed into existing EDK II core packages, which include
120+
`MdePkg`,
121+
122+
**4BThe Basics of EDK II**
123+
124+
`MdeModulePkg`, `IntelFrameworkPkg` and `IntelFrameworkModulePkg`. One reason
125+
is that these packages are published as a base-supported package to facilitate
126+
module/platform development.
127+
128+
**********
129+
**Note:** These packages are open-source code and compliant with the BSD
130+
license. If the developed module is not intended to be open source, it should
131+
not be put into those core packages.
132+
**********
133+
134+
To create a new package, developers must create the DEC file to define the
135+
package's interfaces, including:
136+
137+
* include directories for modules from other packages
138+
139+
* the value of GUIDs
140+
141+
* the value of Protocol GUIDs
142+
143+
* the value of PPI GUIDs
144+
145+
* the declaration of the PCD entries published by this package.
146+
147+
#### 1.1.3.2 Phase 2: Create module metadata/Implement basic functionality.
148+
149+
After the module to be placed into a package is determined, developers must
150+
create an INF file to indicate the module's behavior, including:
151+
152+
* module type
153+
154+
* required library classes
155+
156+
* required ppi/protocol/guid/PCD
157+
158+
* dependency relationship with other modules.
159+
160+
**********
161+
**Note:** Dependency relationships may exist or not, depending on various
162+
module types.
163+
**********
164+
165+
Viewing a module's INF file provides a quick overview to an unfamiliar module.
166+
167+
After finishing the INF file, developers should start writing source code to
168+
implement basic functionality.
169+
170+
**********
171+
**Note:** In $WORKSPACE\MdePkg\Include\Library directory, there are many
172+
library classes to provide support functions. There are also entry point
173+
libraries for various module types. Developers should browse the header files
174+
for details.
175+
**********
176+
177+
#### 1.1.3.3 Phase 3: Create DSC to build
178+
179+
In EDK II, the DSC file describes the build behavior of the package, including:
180+
181+
* modules needed to be built
182+
183+
* chosen library instances for various module type
184+
185+
* the configuration of the PCD entries used by modules.
186+
187+
The single platform DSC and each referenced package's DEC files cooperate to
188+
define a package. These files and the module INF files are required to build
189+
all modules in the package.
190+
191+
#### 1.1.3.4 Phase 4: Tune modules
192+
193+
To tune modules
194+
195+
* use EDK II libraries for code reuse
196+
197+
* use EDK II PCD mechanism for configuration.
198+
199+
The distinction between an EDK module and an EDK II module is that the EDK II
200+
module can be customized either statically or dynamically, as necessary.
201+
202+
* Static customization is preferred to choose the library instance or determine
203+
the value of FeatureFlag/Fixed type of PCD at build time.
204+
205+
* Dynamic customization is preferred for using Patchable/Dynamic type PCD to
206+
control procedure behavior on the fly.
207+
208+
EDK II module developers should consider what logic in the module could be
209+
generalized as early in the development of the module as possible. For example,
210+
if some functionality had been implemented in a library class of a core
211+
package, the developer should replace it by using the library class.
212+
213+
If a segment of logic can be extracted as common logic and shared by various
214+
modules, the developer can create a new library class and instance.
215+
216+
**********
217+
**Note:** In the EDK II module development, developers are strongly discouraged
218+
from using a conditional macro to control procedure behavior. The PCD mechanism
219+
provides a unified interface, and developers should use it to configure a
220+
module's behavior.
221+
**********
222+
223+
### 1.1.4 Build Infrastructure
224+
225+
The EDK II build system is based on Python and portable C code to provide
226+
crossplatform build-ability. Figure 1, developer illustrates the conceptual
227+
workflow of the EDK II build system infrastructure.
228+
229+
**4BThe Basics of EDK II**
230+
231+
![](../media/image1.jpg)
232+
233+
###### Figure 1 Conceptual workflow
234+
235+
In brief, the EDK II build tool parses the metadata files (DSC, DECs, and
236+
INFs) to generate corresponding one top-level makefile and a separate set of
237+
makefile and autogen.c/autogen.h files for every module.
238+
239+
In the autogen files, the EDK II build tool generates all definitions of guids,
240+
protocols, ppis, and PCDs used by the module, and automatically invokes all of
241+
the constructors of used library instances in the module's entry point
242+
implementations.

Diff for: ‎1_the_basics_of_edk_ii/12_related_references.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
<!--- @file
2+
1.2 Related References
3+
4+
Copyright (c) 2010-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 1.2 Related References
33+
34+
The following publications and sources of information may be useful or are
35+
referred to by this document:
36+
37+
* _Unified Extensible Firmware Interface Specification_ Version 2.1, Unified
38+
EFI, Inc, 2007, http://www.uefi.org.
39+
40+
* _Extensible Firmware Interface Specification_ Version 1.10, Intel, 2001,
41+
http://developer.intel.com/technology/efi.
42+
43+
* _Intel(R) Platform Innovation Framework for EFI Specifications_, Intel, 2006,
44+
[http://www.intel.com/technology/framework/.](http://www.intel.com/technology/framework/)
45+
46+
The following publications are available at edk2.tianocore.org:
47+
48+
* _EDK II MDE (Module Development Environment) Package Document_, Version
49+
50+
1.00, Intel, 2006.
51+
52+
* _EDK II DSC File Specification_, Version 0.50, Intel, 2007.
53+
54+
* _EDK II DEC File Specification_, Version 0.50, Intel, 2007.
55+
56+
* _EDK II Extended INF Specification_, Version 0.50, Intel, 2007.
57+
58+
* _EDK II FDF (Flash Description File) File Specification_, Version 0.50,
59+
Intel, 2007.
60+
61+
* _EDK II Build Specification_, Version 1.00, Intel, 2008.

Diff for: ‎1_the_basics_of_edk_ii/13_terms.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<!--- @file
2+
1.3 Terms
3+
4+
Copyright (c) 2010-2018, Intel Corporation. All rights reserved.<BR>
5+
6+
Redistribution and use in source (original document form) and 'compiled'
7+
forms (converted to PDF, epub, HTML and other formats) with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1) Redistributions of source code (original document form) must retain the
11+
above copyright notice, this list of conditions and the following
12+
disclaimer as the first lines of this file unmodified.
13+
14+
2) Redistributions in compiled form (transformed to other DTDs, converted to
15+
PDF, epub, HTML and other formats) must reproduce the above copyright
16+
notice, this list of conditions and the following disclaimer in the
17+
documentation and/or other materials provided with the distribution.
18+
19+
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
20+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21+
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
22+
EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24+
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25+
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26+
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
28+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
30+
-->
31+
32+
## 1.3 Terms
33+
34+
The following terms are used throughout this document to describe varying
35+
aspects of input localization:
36+
37+
**EDK**
38+
39+
EFI Developer's kit; the open source project of the Intel Platform Innovation
40+
Framework for EFI that can be found at
41+
[http://edk.tianocore.org.](http://edk.tianocore.org/)
42+
43+
**EDK II**
44+
45+
A generic term to describe the open source project found at
46+
47+
[http://edk2.tianocore.org.](http://edk2.tianocore.org/) In this document, it
48+
refers to the new release of EDK II that supports a build infrastructure that
49+
makes use of the Extended INF, DEC and Extended DSC.
50+
51+
**EDK II Module**
52+
53+
A generic term to describe a module that is developed using the new release of
54+
EDK II project that supports the library class, library instances, packaging
55+
concept and Extended INF, DEC and Extended DSC files.

0 commit comments

Comments
 (0)