1eaf341c |
1 | This directory contains the next generation of EDK II build tools and template files.\r |
2 | Templates are located in the Conf directory, while the tools executables for\r |
3 | Microsoft Windows 32-bit Operating Systems are located in the Bin\Win32 directory.\r |
4 | \r |
5 | The binary tools will be updated only after passing developer testing.\r |
6 | \r |
7 | The BaseTools package will be updated with new tools only after all testing on a set\r |
8 | of binary tools has successfully completed.\r |
9 | \r |
10 | Current state of the tools is Proto-Type - not all tool functions have been implemented\r |
11 | and there may be bugs in these tools. These tools are under constant development at\r |
12 | this time.\r |
13 | \r |
14 | BaseTools Simple Usage:\r |
15 | 1) Change the directory to the EDK2 root directory, where the edksetup.bat is\r |
16 | 2) Run "edksetup.bat NewBuild"\r |
17 | 3) Set the ACTIVE_PLATFORM to your desired platform description file \r |
18 | (%WORKSPACE%\Conf\target.txt)\r |
19 | 4) To build platform, run "build" command in non-module directory\r |
20 | 5) To build module individually, run "build" command in module directory, i.e. where the \r |
21 | *.inf file is\r |
22 | \r |
23 | Notes:\r |
24 | 1) The tree structure generated by build tools is similar to Ant build system.\r |
25 | 2) Makefile can be called directly by nmake for both top level platform and module. But\r |
26 | after you call "nmake cleanall", you have to call "build" command to rebuild platform\r |
27 | or modules because the AutoGen.* files have been be removed. The "makefile" itself\r |
28 | cannot generate AutoGen.* files. Only "build" command can.\r |
29 | 3) build.exe in %WORKSPACE%\BaseTools\Bin\Win32 is generated from following revision of\r |
30 | Python source code:\r |
31 | r817 <buildtools_project>\BaseTools\Source\Python\Autogen\r |
32 | r817 <buildtools_project>\BaseTools\Source\Python\build\r |
33 | r817 <buildtools_project>\BaseTools\Source\Python\Common\r |
34 | r817 <buildtools_project>\BaseTools\Source\Python\CommonDataClass\r |
35 | r817 <buildtools_project>\BaseTools\Source\Python\GenFds\r |
36 | \r |
37 | 4) GenFds.exe has is a combo of the follow python source.(This is a temporary branch)\r |
38 | r816 <buildtools_project>\BaseTools\Source\Python\Common\r |
39 | r816 <buildtools_project>\BaseTools\Source\Python\CommonDataClass\r |
40 | r816 <buildtools_project>\BaseTools\Source\Python\GenFds\r |
41 | \r |
42 | Brief usage for Migration Tool MigrationMsa2Inf.exe:\r |
43 | 1. Command line format:\r |
44 | MigrationMsa2Inf [options]\r |
45 | 2. Input Files:\r |
46 | A syntactically valid MSA file\r |
47 | 3. Output Files:\r |
48 | An extended INF file with possible auto-generated EntryPoint.c, CommonHeader.h/CommonHeader.txt, depending on options and module contents.\r |
49 | 4. Prerequisite:\r |
50 | a. The workspace directory must be specified either by environment variable or -w option. \r |
51 | b. The Framework Database file must exist to specify the available packages in current workspace. \r |
52 | Two possible locations are: (The first location overrides the second)\r |
53 | $(WORKSPACE)\Tools\Conf\FrameworkDatabase.db\r |
54 | $(WORKSPACE)\Conf\FrameworkDatabase.db. \r |
55 | The <PackageList> field in FrameworkDatabase.db lists all available packages in current workspace. \r |
56 | One example:\r |
57 | <PackageList>\r |
58 | <Filename>MdePkg/MdePkg.nspd</Filename>\r |
59 | <Filename>MdeModulePkg/MdeModulePkg.spd</Filename>\r |
60 | <Filename>IntelFrameworkPkg/IntelFrameworkPkg.spd</Filename>\r |
61 | </PackageList>\r |
62 | The package list in FrameworkDatabase.db is important to the final quality of migration:\r |
63 | (1) It suggests the new package location: Translate package dependency Guid in MSA to Workspace relative path. \r |
64 | If the package dependency Guid cannot be found in current workspace a warning message is raised. \r |
65 | (2) It collects the Protocol/Guid/Ppi GuidCName a package contains. \r |
66 | The GuidCName acts as "clue" to add e.g. #include <Protocol/DiskIo.h> in CommonHeader.h\r |
67 | \r |
68 | 5. Example:\r |
69 | WORKSAPCE has already been set: $(WORKSPACE) = c:\work\EdkII. \r |
70 | \r |
71 | a. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -o c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.inf\r |
72 | b. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -a\r |
73 | Example a & b are equivalent to migrate WinNtThunk driver from EDKII to EDKII' code base.\r |
74 | \r |
75 | c. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -a -c\r |
76 | The extra "-c" option performs several hardcode mapping due to the naming change in EDKII': \r |
77 | OldMdePkg Guid -> MdePkgGuid, \r |
78 | EdkModulePkg Guid -> MdeModulePkgGuid, \r |
79 | EdkGraphicsLib -> GraphicsLib\r |
80 | HiiLib -> HiiLibFramework\r |
81 | ...\r |
82 | \r |
83 | d. MigrationMsa2Inf -f c:\work\EdkII\Nt32Pkg\WinNtThunkDxe\WinNtThunk.msa -m\r |
84 | The extra "-m" option suppresses the generation of "CommonHeader.h" and leave all C files intact. \r |
85 | Instead, it generates "CommonHeader.txt". Developers can manually copy its content to a local common header file in a module. \r |
86 | \r |
87 | 6. Known Limitations:\r |
88 | a. Tool does not handle Exit Boot Services Callback & Virtual Address Changed Event. Developers need to handle it manually.\r |
89 | b. The #include <Library/AbcLib.h> is based on library class naming convention: The header filename for "AbcLib" class are "AbcLib.h" by convention.\r |
90 | c. The #include <Guid/Xyz.h>, <Protocol/Xyz.h> and <Ppi/Xyz.h> are added based on gGuidCName listed in MSA. \r |
91 | If a GuidCName cannot map to a package Guid/Protocol/Ppi header file, a warning message is raised.\r |
92 | If a module uses the definition in a pakcage Guid/Protocol/Ppi header file without list its associative GuidCName, the build will beak. Developer needs to manually add the include statement.\r |
93 | d. The [Depex] sections are generated from DXS files with Guid Macro translated to Guid CName by naming convention, etc.\r |
94 | If tool fails to "guess" the Guid CName from Guid Macro, it will leave the GuidMacro in [Depex] section for manual resolution.\r |
95 | e. When tool generates [Sources] section, the modifiers for source files are lost. (Need to add proper tool chain, etc)\r |
96 | f. When tool generates [LibraryClasses] section, the recommended library instances are lost. (No impact to build)\r |
97 | \r |
98 | 7. Pyton Source\r |
99 | r682 <buildtools_project>\BaseTools\Source\Python\MigrationMsa2Inf\r |
100 | \r |
101 | \r |
102 | Brief Usage for PcdSyntax Update:\r |
103 | Usage:\r |
104 | PcdSyntaxUpdate.exe <directory_name>\r |
105 | It searches all INF, DEC and DSC file under <directory_name> and update them with the following rules:\r |
106 | 1. Update INF files to conform to INF spec 0.44: \r |
107 | a. Rename PCD section name: e.g. [PcdsFeatureFlag] -> [FeaturePcd]\r |
108 | b. Adjust PCD section item format: e.g. PcdDebugClearMemoryValue|gEfiMdePkgTokenSpaceGuid -> gEfiMdePkgTokenSpaceGuid.PcdDebugClearMemoryValue\r |
109 | c. Update the syntax of binary INF file (not PCD related) \r |
110 | 2. Update DEC files to confirm to DEC spec 0.36\r |
111 | Adjust PCD section item format: e.g. PcdWinNtPhysicalDisk|0x00001000|gEfiNt32PkgTokenSpaceGuid|VOID*|L"E:RW;245760;512"-> gEfiNt32PkgTokenSpaceGuid.PcdWinNtFlashFvRecoverySize|0x0|UINT32|0x00001011\r |
112 | 3. Update DSC files to confirm to DSC spec \r |
113 | a. Adjust string/array typed PCD item format: e.g. PcdWinNtMemorySizeForSecMain|gEfiNt32PkgTokenSpaceGuid|L"64!64"|12 -> gEfiNt32PkgTokenSpaceGuid.PcdWinNtMemorySizeForSecMain|L"64!64"|VOID*|12\r |
114 | b. Adjust non-string/array typed PCD item format: e.g. PcdWinNtBootMode|gEfiNt32PkgTokenSpaceGuid|1 -> gEfiNt32PkgTokenSpaceGuid.PcdWinNtBootMode|1\r |
115 | c. Update the override library class in [Components] section: e.g.\r |
116 | <LibraryClass> {\r |
117 | PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf\r |
118 | }\r |
119 | To \r |
120 | <LibraryClasses> {\r |
121 | PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf\r |
122 | }\r |
123 | \r |
124 | Brief usage for Migration Tool Spd2Dec.exe:\r |
125 | 1. Command line format:\r |
126 | Spd2Dec [options] input_filename\r |
127 | 2. Input File:\r |
128 | A syntactically valid SPD file\r |
129 | 3. Output Files:\r |
130 | A DEC file whose syntax confirms to DEC spec.\r |
131 | \r |
132 | 4. Example:\r |
133 | a. Spd2Dec -o c:\work\EdkII\Nt32Pkg\Nt32.spd c:\work\EdkII\Nt32Pkg\Nt32.dec\r |
134 | b. Spd2Dec -a c:\work\EdkII\Nt32Pkg\Nt32.spd\r |
135 | Example a & b are equivalent to migrate Nt32 package SPD file from EDKII to EDKII' snytax.\r |
136 | \r |
137 | 6. Pyton Source\r |
138 | r777 <buildtools_project>\BaseTools\Source\Python\spd2Dec\r |
139 | \r |
140 | Brief usage for Migration Tool Fpd2Dsc.exe:\r |
141 | 1. Command line format:\r |
142 | Fpd2Dsc [options] input_filename\r |
143 | 2. Input File:\r |
144 | A syntactically valid FPD file\r |
145 | 3. Output Files:\r |
146 | A DSC file which syntax confirms to DSC spec.\r |
147 | 4. Prerequisite:\r |
148 | a. The workspace directory must be specified either by environment variable or -w option.\r |
149 | \r |
150 | 5. Example:\r |
151 | WORKSAPCE has already been set: $(WORKSPACE) = c:\work\EdkII. \r |
152 | \r |
153 | a. Fpd2Dsc -o c:\work\EdkII\Nt32Pkg\Nt32.dsc c:\work\EdkII\Nt32Pkg\Nt32.fpd\r |
154 | b. Fpd2Dsc -a c:\work\EdkII\Nt32Pkg\Nt32.fpd\r |
155 | Example a & b are equivalent to migrate Nt32 platform description file from EDKII to EDKII' snytax.\r |
156 | \r |
157 | 6. Known Limitations:\r |
158 | a. Tool does not handle Libraries Section since no related info in original FPD file. Developers need to handle it manually in the output DSC file.\r |
159 | b. If MSA file which is corresponds to module guid could not be found in currect workspace, tool will dump the module guid.\r |
160 | \r |
161 | 7. Pyton Source\r |
162 | r767 <buildtools_project>\BaseTools\Source\Python\Fpd2Dsc\r |
163 | \r |
164 | 27-September-2007\r |