| 1 | Intel(R) Platform Innovation Framework for EFI\r |
| 2 | EFI Development Kit 2.0 (EDK 2.0) \r |
| 3 | Alpha Release\r |
| 4 | 2006-04-26\r |
| 5 | \r |
| 6 | Copyright (c) 2006, Intel Corporation\r |
| 7 | \r |
| 8 | This document provides updates to documentation, along with a description on \r |
| 9 | how to install and build the Edk 2.0.\r |
| 10 | \r |
| 11 | Package Contents\r |
| 12 | ----------------\r |
| 13 | ReleaseNote.txt- These release notes for the package.\r |
| 14 | MdePkg - A package containing Industry Standard headers and libraries\r |
| 15 | Tools - A package containing Build Specific tools which are designed\r |
| 16 | to help the developer create and modify drivers and\r |
| 17 | libraries\r |
| 18 | EdkModulePkg - A package containing reference drivers\r |
| 19 | EdkFatBinPkg - A package containing binary DXE drivers for the Fat 32 file\r |
| 20 | system\r |
| 21 | EdkShellBinPkg - A package containing binary Shell applications and commands\r |
| 22 | EdkNt32Pkg - A package containing the NT32 Emulation platform reference\r |
| 23 | \r |
| 24 | Note: MDE and MDK that appear in other documentation refer to the MdePkg and\r |
| 25 | Tools packages. These two packages are the minimum requirement for developing\r |
| 26 | EDK 2.0 Packages. It is also recommended that the top level files included\r |
| 27 | with the EDK be downloaded in conjunction with these two packages.\r |
| 28 | \r |
| 29 | Note: Documents have the following filenames:\r |
| 30 | EDK 2.0 Module Development Environment Library Specification v0.50 \r |
| 31 | (MDE_Library_Spec_0_50.rtf)\r |
| 32 | EDK 2.0 Build and Packaging Architecture Specification v0.50\r |
| 33 | (Build_Packaging_Spec_0_50.rtf)\r |
| 34 | EDK 2.0 Platform Configuration Database Infrastructure Description v0.51\r |
| 35 | (PCD_Infrastructure_0_51.rtf)\r |
| 36 | EDK 2.0 Module Surface Area v0.50\r |
| 37 | (Module_Surface_Area_0_50.rtf)\r |
| 38 | EDK 2.0 Module Development Environment (MDE) Package Specification v0.50\r |
| 39 | (MDE_Package_Spec_0_50.rtf)\r |
| 40 | EDK 2.0 C Coding Standards Specification v0.50\r |
| 41 | (C_Coding_Standards_Specification_ 0_50.rtf)\r |
| 42 | \r |
| 43 | Pre-Requisites\r |
| 44 | --------------\r |
| 45 | The following list of tools must be installed on the development workstation\r |
| 46 | prior to using the Edk 2.0.\r |
| 47 | \r |
| 48 | Compiler Tool Chain\r |
| 49 | Microsoft* Visual Studio .NET 2003* (http://www.microsoft.com)\r |
| 50 | or\r |
| 51 | GCC version 4.x or later (http://gcc.gnu.org)\r |
| 52 | \r |
| 53 | Assembler Tool Chain\r |
| 54 | Microsoft Macro Assembler, version 6.15 or later\r |
| 55 | or\r |
| 56 | GCC version 4.x or later\r |
| 57 | \r |
| 58 | Java Development Kit ( Java 5.0 or later)\r |
| 59 | Sun* jdk-1.5.0_04 or later (http://java.sun.com)\r |
| 60 | or\r |
| 61 | Bea Systems* jrockit-25.2.0-jdk1.5.0_03 or later (http://www.bea.com)\r |
| 62 | \r |
| 63 | Java Tools\r |
| 64 | Apache-ANT, version 1.6.5 or later (http://ant.apache.org)\r |
| 65 | Ant-contrib, version 1.0b2 or later (http://antcontrib.sourceforge.net)\r |
| 66 | Saxon8, version 8.1.1\r |
| 67 | (http://prdownloads.sourceforge.net/saxon/saxonb8-1-1.zip?download)\r |
| 68 | XMLBeans, version 2.1.0 or later (http://xmlbeans.apache.org) \r |
| 69 | \r |
| 70 | Other Tools\r |
| 71 | TortoiseSVN version 1.3.3. (http://tortoisesvn.tigris.org/)\r |
| 72 | \r |
| 73 | Optional Tools\r |
| 74 | --------------\r |
| 75 | Compiler Tool Chains:\r |
| 76 | Intel C++ Compiler for Windows, ver. 9.0 or later (http://www.intel,com)\r |
| 77 | Intel C Compiler for EFI Byte Code, ver. 1.2 or later\r |
| 78 | Microsoft Driver Development Kit, version 3790.1830 or later\r |
| 79 | Microsoft ACPI Source Language Assembler, Version 1.0.13NT or later\r |
| 80 | Intel ACPI Component Architecture, version 20060113\r |
| 81 | \r |
| 82 | -----------------------\r |
| 83 | Notes On Required Tools (Source Control System)\r |
| 84 | -----------------------\r |
| 85 | The EDK 2.0 is being managed by the Subversion Source Control on Tianocore.org.\r |
| 86 | This software package provides speed, security, and additional features. The\r |
| 87 | recommended client is TortoiseSVN version 1.3.3. \r |
| 88 | (Available at http://tortoisesvn.tigris.org/)\r |
| 89 | \r |
| 90 | There are instructions for the use of Subversion Source Control on the\r |
| 91 | Tianocore.org website, as part of the checkout procedures.\r |
| 92 | \r |
| 93 | The URL of the EDK 2.0 repository is:\r |
| 94 | https://edk2.tianocore.org/svn/edk2/trunk/edk2\r |
| 95 | \r |
| 96 | -----------------------\r |
| 97 | Notes On Documentation\r |
| 98 | -----------------------\r |
| 99 | The documents are being managed by the Subversion Source Control on\r |
| 100 | Tianocore.org. The document repository is "docs" and must be checked out\r |
| 101 | separately from the EDK 2.0 source tree. Refer to the checkout procedures on\r |
| 102 | the Tianocore.org website for EDK 2.0.\r |
| 103 | \r |
| 104 | The URL of the document repository is:\r |
| 105 | https://edk2.tianocore.org/svn/edk2/trunk/docs\r |
| 106 | \r |
| 107 | \r |
| 108 | -----------------------\r |
| 109 | Notes On Required Tools (MS Windows environment example)\r |
| 110 | -----------------------\r |
| 111 | Software Installation Order:\r |
| 112 | After installing the compiler tools and your Subversion client, the following\r |
| 113 | required tools should be installed in order: \r |
| 114 | Java JDK, Apache-Ant, ant-contrib, xmlbeans, saxon8\r |
| 115 | \r |
| 116 | Java Development Kit:\r |
| 117 | \r |
| 118 | The Java Environment Variable must be set before attempting to build.\r |
| 119 | i.e. For Sun JDK (see note below*):\r |
| 120 | set JAVA_HOME=c:\ Java\jdk1.5.0_06 \r |
| 121 | i.e. For Bea Systems:\r |
| 122 | set JAVA_HOME=c:\Program Files\Java\jrockit-R26.0.0-jdk1.5.0_04\r |
| 123 | \r |
| 124 | *When using the Sun JDK5.0\r |
| 125 | During installation, you should specify the install directory as C:\Java\r |
| 126 | instead of C:\Program Files\(or some other drive letter.) While installing\r |
| 127 | to this non-standard location is not required. In use, it seems to work \r |
| 128 | more reliably. \r |
| 129 | For the JDK, the install path would be C:\Java\jdk1.5.0_06\r |
| 130 | For the JRE, the install path would be C:\Java\jre1.5.0_06\r |
| 131 | Alternatively, you can specify C:\sunjavajdk and C:\sunjavajre.\r |
| 132 | NOTE: You cannot combine the location for the JDK and the JRE, as the JRE\r |
| 133 | install removes most of the binaries and libraries installed by the JDK\r |
| 134 | install.\r |
| 135 | \r |
| 136 | Java Tools:\r |
| 137 | The Apache-ANT requires the ANT_HOME environment variable to be set before\r |
| 138 | attempting to build:\r |
| 139 | i.e. set ANT_HOME=c:\ant\r |
| 140 | \r |
| 141 | The ant-contrib.jar file should be installed in the %ANT_HOME%\lib \r |
| 142 | directory.\r |
| 143 | \r |
| 144 | The XMLBeans, requires the XMLBEANS_HOME environment variable to be set\r |
| 145 | before attempting to build:\r |
| 146 | i.e. set XMLBEANS_HOME=C:\XMLBEANS \r |
| 147 | \r |
| 148 | The saxon8.jar file should be copied to the %XMLBEANS_HOME%\lib directory.\r |
| 149 | \r |
| 150 | The Ant and XMLBean tools are required to be in the path.\r |
| 151 | MS system example:\r |
| 152 | set PATH=%PATH%;%ANT_HOME%\bin;%XMLBEANS_HOME%\bin\r |
| 153 | Linux/OS X bash shell example:\r |
| 154 | export PATH=$PATH:${ANT_HOME}/bin:${XMLBEANS_HOME}/bin\r |
| 155 | \r |
| 156 | -------------------------------------------------------------------------------\r |
| 157 | Quick Start\r |
| 158 | -----------\r |
| 159 | Edit the text file, tools_def.txt, located in the Tools/Conf directory. This\r |
| 160 | file contains the names of the compiler tool chains and the location of the\r |
| 161 | compiler binaries. It has been pre-populated with the standard location for\r |
| 162 | the Microsoft tool chains and includes the standard location of the Intel C \r |
| 163 | Compiler for EFI Byte Code (EBC)\r |
| 164 | \r |
| 165 | Follow the instructions at https://edk2.tianocore.org/servlets/ProjectSource to\r |
| 166 | checkout the entire EDK 2.0 source tree.\r |
| 167 | \r |
| 168 | In a command window, change to the top level directory of the Edk 2.0 sources.\r |
| 169 | Set the WORKSPACE environment variable, e.g.:\r |
| 170 | \r |
| 171 | c:\> set WORKSPACE=C:\MyWork\Edk2.0\r |
| 172 | \r |
| 173 | To test your tool chain setup and to build the Supplied Tools, execute:\r |
| 174 | c:\MyWork\Edk2.0\> edksetup\r |
| 175 | \r |
| 176 | (This command will be referred to as the setup command throughout the rest of\r |
| 177 | this document.)\r |
| 178 | NOTE: You should run the setup command at the start of every session.\r |
| 179 | This configures the environment to include the TianoTools and the\r |
| 180 | Java applications and libraries.\r |
| 181 | \r |
| 182 | Once this is completed, you are ready to test the Build, by executing:\r |
| 183 | c:\MyWork\Edk2.0\> ant\r |
| 184 | \r |
| 185 | This command builds all of the packages, including the NT32 reference platform.\r |
| 186 | \r |
| 187 | -------------------------\r |
| 188 | Individual Package Builds\r |
| 189 | -------------------------\r |
| 190 | After running the setup command, you can build individual packages.\r |
| 191 | In the command window, cd to the package that you want to build, and just\r |
| 192 | type:\r |
| 193 | c:\MyWork\Edk2.0\EdkNt32Pkg\> ant\r |
| 194 | \r |
| 195 | The EdkNt32Pkg has a special target; "run" that will execute the Nt32 emulation\r |
| 196 | platform under Microsoft Windows.\r |
| 197 | \r |
| 198 | ------------------------\r |
| 199 | Individual Module Builds\r |
| 200 | ------------------------\r |
| 201 | After running the setup command, you can build individual modules.\r |
| 202 | In the command window, cd to the module that you want to build, and just\r |
| 203 | type:\r |
| 204 | c:\MyWork\Edk2.0\MdePkg\Library\BaseLib\> ant\r |
| 205 | \r |
| 206 | -------------------------------------------------------------------------------\r |
| 207 | A Word on Apache-ANT\r |
| 208 | --------------------\r |
| 209 | The Apache-ANT program is a build tool that uses XML-based project files.\r |
| 210 | Similar to Makefiles, these project files may contain multiple targets. Most\r |
| 211 | build.xml files in Edk2.0 are auto-generated; any edits performed on the\r |
| 212 | build.xml files will be overwritten the next time ant is executed.\r |
| 213 | \r |
| 214 | Pre-defined targets in the build.xml files include:\r |
| 215 | all - This target builds binaries for defined architectures\r |
| 216 | clean - This target removes object files generated by commands\r |
| 217 | cleanall - This target removes all generated files and directories.\r |
| 218 | \r |
| 219 | A Word on GCC tool chain\r |
| 220 | ------------------------\r |
| 221 | You will find a script in the tree that will download, configure, compile, and\r |
| 222 | install a gcc 4.0.2 tool chain for development. It has support for the ia32\r |
| 223 | architecture. It can be built and run on Cygwin, Linux, and many other POSIX\r |
| 224 | compliant host environments. There are a few tools that you will need on your\r |
| 225 | host computer in order to compile the tool chain. Among them are bash, gcc,\r |
| 226 | gmake, curl (or wget).\r |
| 227 | \r |
| 228 | -------------------------------------------------------------------------------\r |
| 229 | \r |
| 230 | General Information:\r |
| 231 | =============================================================== \r |
| 232 | Mechanisms:\r |
| 233 | ----------\r |
| 234 | A quick understanding:\r |
| 235 | \r |
| 236 | A) Surface Area Package Description (SPD) file contains information about the\r |
| 237 | modules that the package contains, including the location of all MSA files, and\r |
| 238 | public library names and headers that might be provided by a module in the\r |
| 239 | package. Packages are defined by SPD files. (Found in the root of the Package\r |
| 240 | subdirectory (i.e. EdkNt32Pkg)) The SPD is further explained in the "Build \r |
| 241 | Packaging Specification" document.\r |
| 242 | \r |
| 243 | B) Module Surface Area Definition (MSA) files. A description of a module's \r |
| 244 | surface area, with all module specific default flags and features specified.\r |
| 245 | Refer to the "Module Surface Area Architecture Specification" for additional\r |
| 246 | details. The MSA is further explained in the "Build Packaging Specification"\r |
| 247 | document.\r |
| 248 | \r |
| 249 | C) Module Build Description (MDB). The "as-built" definition file that contains\r |
| 250 | only the changes to the default flags defined in the MSA. The MSA and MDB are\r |
| 251 | further explained in the "Build Packaging Specification" document.\r |
| 252 | \r |
| 253 | D) Platform Configuration Database (PCD). A platform database which contains a\r |
| 254 | variety of current platform settings or directives by which a driver or\r |
| 255 | application can interact with. The PCD is defined by the PCD_Protocol (This is\r |
| 256 | further explained in the "Platform Configuration Database Infrastructure \r |
| 257 | Description" document.\r |
| 258 | \r |
| 259 | E) Library Class. A library class is a logical grouping of similar functions.\r |
| 260 | When developing components, the module surface area declares the class of\r |
| 261 | libraries that can be used by the component. The MBD file specifies the\r |
| 262 | instance(s) of the library that will be used during compilation/linking. All\r |
| 263 | library type modules must include header files in their distribution package,\r |
| 264 | as well as their surface area and module build description files. Components,\r |
| 265 | on the other hand, need only provide the binary and build description files\r |
| 266 | when distributing BINARY packages. The Library Classes are further explained\r |
| 267 | in the "Build Packaging Specification" document.\r |
| 268 | \r |
| 269 | =========================================================================\r |
| 270 | The common operations by developers of new modules are:\r |
| 271 | -------------------------------------------------------\r |
| 272 | \r |
| 273 | 1) How to manually create a new module in a package:\r |
| 274 | - The module source code must first be created in an appropriate directory\r |
| 275 | (under the package the module is to be a part of.) \r |
| 276 | - An MSA file must be created, spelling out all aspects of the module.\r |
| 277 | - The MSA must be added to the SPD for the package to include the module.\r |
| 278 | \r |
| 279 | -----------------------------------------\r |
| 280 | 2) Add/Remove module(s) to/from a package:\r |
| 281 | \r |
| 282 | - Setup environment as Build\r |
| 283 | - Add a module to a package\r |
| 284 | * Generate the module SurfaceArea description file and build description\r |
| 285 | file\r |
| 286 | * Run GenBuildFile.bat under <PackageDir> to generate an entrance\r |
| 287 | build.xml for the module\r |
| 288 | * Add a new <MsaFile> element under <MsaFiles> into\r |
| 289 | <PackageDir>\<PackageName>.spd, using relative path to package\r |
| 290 | * Add a new <ModuleSA> entry under each <TianoImage> into\r |
| 291 | <PackageDir>\<PackageName>.fpd file\r |
| 292 | \r |
| 293 | - Remove a module from a package\r |
| 294 | * Comment out or remove corresponding <MsaFile> element under <MsaFiles>\r |
| 295 | from <PackageDir>\<PackageName>.spd\r |
| 296 | * Comment out or remove corresponding <ModuleSA> entry under each\r |
| 297 | <TianoImage> from <PackageDir>\<PackageName>.fpd\r |
| 298 | \r |
| 299 | -----------------------------------\r |
| 300 | 3) How to manually create a package:\r |
| 301 | - Identify the modules that are to be members of the project.\r |
| 302 | - Identify the Variables and Guids required in and of the Package (including\r |
| 303 | consumption/production information).\r |
| 304 | - Create an SPD file defining these modules and calling out their MSA files.\r |
| 305 | \r |
| 306 | --------------------------------------\r |
| 307 | 4) Declare a new Protocol in a package: \r |
| 308 | - This release requires manual editing of the SPD file, adding the protocol\r |
| 309 | to the ProtocolDeclarations section of the file. \r |
| 310 | - Add the Protocol .h file to the Include\Protocol directory.\r |
| 311 | - Add an entry to the Protocol.info file\r |
| 312 | * Each line contains Protocol base name then the global variable name and\r |
| 313 | then the hex value of the Protocol GUID.\r |
| 314 | \r |
| 315 | Example Protocol.info file (2 lines):\r |
| 316 | UnicodeCollation gEfiUnicodeCollationProtocolGuid\r |
| 317 | { 0x1d85cd7f, 0xf43d, 0x11d2, 0x9a, 0xc, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \r |
| 318 | UsbHc gEfiUsbHcProtocolGuid\r |
| 319 | { 0xf5089266, 0x1aa0, 0x4953, 0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 }\r |
| 320 | \r |
| 321 | ---------------------------------\r |
| 322 | 5) Declare a new PPI in a package:\r |
| 323 | - This release requires manual editing of the SPD file\r |
| 324 | - Add the PPI .h file to the Include\Ppi directory.\r |
| 325 | - Add an entry to the Ppi.info file\r |
| 326 | * Each line contains PPI base name then the global variable name and then\r |
| 327 | the hex value of the PPI GUID.\r |
| 328 | \r |
| 329 | Example Ppi.info file (2 lines):\r |
| 330 | NtPeiLoadFile gNtPeiLoadFilePpiGuid\r |
| 331 | { 0xfd0c65eb, 0x405, 0x4cd2, 0x8a, 0xee, 0xf4, 0x0, 0xef, 0x13, 0xba, 0xc2 }\r |
| 332 | NtThunk gPeiNtThunkPpiGuid\r |
| 333 | { 0x98c281e5, 0xf906, 0x43dd, 0xa9, 0x2b, 0xb0, 0x3, 0xbf, 0x27, 0x65, 0xda }\r |
| 334 | \r |
| 335 | ----------------------------------\r |
| 336 | 6) Declare a new GUID in a package:\r |
| 337 | - This release requires manual editing of the SPD file to include the new\r |
| 338 | Guid.\r |
| 339 | \r |
| 340 | --------------------------------------- \r |
| 341 | 7) Declare a new PCD entry in a package:\r |
| 342 | - This release requires manual editing of the SPD file to include the new\r |
| 343 | PCD.\r |
| 344 | \r |
| 345 | ------------------------------\r |
| 346 | 8) Declare a new Library Class:\r |
| 347 | - This release requires manual editing of the SPD file to include the new\r |
| 348 | Library Class.\r |
| 349 | \r |
| 350 | --------------------------------------\r |
| 351 | 9) Add a library instance to a package:\r |
| 352 | - This requires manual MSA and MBD file.\r |
| 353 | \r |
| 354 | -----------------------------\r |
| 355 | 10) Add a module to a package:\r |
| 356 | - This requires manual MSA and MBD editing\r |
| 357 | \r |
| 358 | \r |
| 359 | =======================================================\r |
| 360 | Notes:\r |
| 361 | ------\r |
| 362 | The EDK 2.0 represents significant changes in the structure of the EDK.\r |
| 363 | Therefore it is very difficult to isolate all of the changes of this version of\r |
| 364 | the EDK with the previous (EDK 1.0) version.\r |
| 365 | \r |
| 366 | Of particular note:\r |
| 367 | \r |
| 368 | 1) EDK 2.0 contains new hardware feature support for the ICH SMBUS Libraries.\r |
| 369 | These libraries are provided to make Memory Reference Code (MRC) development\r |
| 370 | easier.\r |
| 371 | 2) The MDE Libraries - The MDE libraries resent significant changes in source\r |
| 372 | (with only limited changes in functionality.) These new libraries conform\r |
| 373 | to the "MDE Library Specification". \r |
| 374 | 3) The Fat Binary and the EDK Shell Binary Packages are functionally identical\r |
| 375 | to the EDK 1.0 version.\r |
| 376 | 4) The EDK tools directory has been expanded to include more tools and more\r |
| 377 | tool functionality.\r |
| 378 | 5) The EDK NT32 section has been ported to the new build process, but\r |
| 379 | functionally remains the same as the EDK 1.0 version.\r |
| 380 | 6) The Application "HelloWorld" has been ported to EDK 2.0 as well.\r |
| 381 | \r |
| 382 | =======================================================\r |
| 383 | Virus scanned by McAfee VirusScan Enterprise 8.0.0, Virus Definitions 4718, no\r |
| 384 | virus detected.\r |
| 385 | \r |