From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=192.55.52.115; helo=mga14.intel.com; envelope-from=michael.d.kinney@intel.com; receiver=edk2-devel@lists.01.org Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 18754211C280B for ; Tue, 5 Feb 2019 09:17:22 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 05 Feb 2019 09:17:21 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.58,336,1544515200"; d="scan'208";a="136103207" Received: from orsmsx103.amr.corp.intel.com ([10.22.225.130]) by orsmga001.jf.intel.com with ESMTP; 05 Feb 2019 09:17:21 -0800 Received: from orsmsx162.amr.corp.intel.com (10.22.240.85) by ORSMSX103.amr.corp.intel.com (10.22.225.130) with Microsoft SMTP Server (TLS) id 14.3.408.0; Tue, 5 Feb 2019 09:17:20 -0800 Received: from orsmsx113.amr.corp.intel.com ([169.254.9.240]) by ORSMSX162.amr.corp.intel.com ([169.254.3.39]) with mapi id 14.03.0415.000; Tue, 5 Feb 2019 09:17:21 -0800 From: "Kinney, Michael D" To: "Kubacki, Michael A" , "edk2-devel@lists.01.org" CC: "Desimone, Nathaniel L" , "Sinha, Ankit" , "Chiu, Chasel" , "Oram, Isaac W" , "Gao, Liming" Thread-Topic: [edk2-platforms/devel-MinPlatform][PATCH v3 1/1] ReadMe.md: Update Minimum Platform details Thread-Index: AQHUvPYtYbIEEvnUMkCcH98mmqEd4qXRc1nw Date: Tue, 5 Feb 2019 17:17:20 +0000 Message-ID: References: <20190205015725.45656-1-michael.a.kubacki@intel.com> In-Reply-To: <20190205015725.45656-1-michael.a.kubacki@intel.com> Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: dlp-product: dlpe-windows dlp-version: 11.0.400.15 dlp-reaction: no-action x-originating-ip: [10.22.254.138] MIME-Version: 1.0 Subject: Re: [edk2-platforms/devel-MinPlatform][PATCH v3 1/1] ReadMe.md: Update Minimum Platform details X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 X-List-Received-Date: Tue, 05 Feb 2019 17:17:22 -0000 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Reviewed-by: Michael D Kinney > -----Original Message----- > From: Kubacki, Michael A > Sent: Monday, February 4, 2019 5:57 PM > To: edk2-devel@lists.01.org > Cc: Kinney, Michael D ; > Desimone, Nathaniel L ; > Sinha, Ankit ; Chiu, Chasel > ; Oram, Isaac W > ; Gao, Liming > > Subject: [edk2-platforms/devel-MinPlatform][PATCH v3 > 1/1] ReadMe.md: Update Minimum Platform details >=20 > Adds details on the EDK II Minimum Platform design for > Intel > platforms. >=20 > * Overview of Minimum Platform > * Board package purpose and conventions > * Stage boot concept and control > * Minimum Platform firmware solution stack overview > * Updates build instructions for all OpenBoardPkgs > * Adds information for the ClevoOpenBoardPkg > * Adds planned activities and ideas for the future >=20 > Cc: Michael D Kinney > Cc: Nate DeSimone > Cc: Ankit Sinha > Cc: Chasel Chiu > Cc: Isaac W Oram > Cc: Liming Gao >=20 > Contributed-under: TianoCore Contribution Agreement 1.0 > Signed-off-by: Michael Kubacki > > --- > ReadMe.md | 164 > ++++++++++++++++++++++++++++++++++++++++++++++++++----- > ------- > 1 file changed, 132 insertions(+), 32 deletions(-) >=20 > diff --git a/ReadMe.md b/ReadMe.md > index 9b873da2e3..72e332a476 100644 > --- a/ReadMe.md > +++ b/ReadMe.md > @@ -1,8 +1,73 @@ > -# **EDK II Minimized firmware for Intel(R) platforms** > +# **EDK II Minimum Platform Firmware for Intel(R) > Platforms** >=20 > -## Features > -* The Minimized Kabylake provides the minimal feature > of the Kabylake BIOS. > -* The Minimized Purley provides the minimal feature of > the Purley BIOS. > +The Minimum Platform is a software architecture that > guides uniform delivery of Intel platforms enabling > firmware > +solutions for basic boot functionality with > extensibility built-in. > + > +Package maintainers for the Minimum Platform projects > are listed in Maintainers.txt. > + > +## Overview > +The key elements of the architecture are organized > into a staged boot approach where each stage has > requirements and > +functionality for specific use cases. The generic > control flow through the boot process is implemented in > the > +[`MinPlatformPkg`](https://github.com/tianocore/edk2- > platforms/tree/devel- > MinPlatform/Platform/Intel/MinPlatformPkg). > +The generic nature of the tasks performed in > MinPlatformPkg lends to reuse across all Intel > platforms with no > +source modification. Details for any particular board > are made accessible to the MinPlatformPkg through a > well-defined > +statically linked board API. A complete platform > solution then consists of the MinPlatformPkg and a > compatible board > +package. > + > +## Board Naming Convention > +The board packages supported by Intel follow the > naming convention \OpenBoardPkg where xxx refers > to the > +encompassing platform name for a particular platform > generation. For example, the > [`KabylakeOpenBoardPkg`](https://github.com/tianocore/e > dk2-platforms/tree/devel- > MinPlatform/Platform/Intel/KabylakeOpenBoardPkg) > contains the > +board code for Intel Kaby Lake reference systems. > Intel uses the moniker "OpenBoardPkg" to indicate that > this package > +is the open source board code. A closed source > counterpart may exist which simply uses "BoardPkg". > Both directly use > +the MinPlatformPkg from edk2-platforms. > + > +## Stage Selection > +Stage selection is controlled via the PCD > `gMinPlatformPkgTokenSpaceGuid.PcdBootStage` in > [`MinPlatformPkg.dec`](https://github.com/tianocore/edk > 2-platforms/blob/devel- > MinPlatform/Platform/Intel/MinPlatformPkg/MinPlatformPk > g.dec). > +The stage should be configured in the board package > DSC file to the appropriate value. For example, a board > may disable > +all advanced features by setting this value to 4 > instead of 6. This may be used to improve boot time for > a particular > +use case. Decrementing the stage can also be used for > debug since only the actions required for that stage > objective > +should be executed. As an example, ACPI initialization > is not required for a Stage 3 boot. > + > +The stages are defined as follows: > + > +| Stage | Functional Objective | Example > Capabilities > | > +| -------|------------------------------|------------- > ------------------------------------------------------- > --------------------------------| > +| I | Minimal Debug | Serial port > output, source debug enabled, hardware debugger enabled > | > +| II | Memory Functional | Basic > hardware initialization necessary to reach memory > initialization, permanent memory available | > +| III | Boot to UI | Simple > console input and output to a UI, UEFI shell > | > +| IV | Boot to OS | Boot an > operating system with the minimally required features > | > +| V | Security Enable | UEFI Secure > Boot, TCG measured boot, DMA protections > | > +| VI | Advanced Feature Enable | Firmware > update, power management, non-essential I/O > | > + > +## Minimum Platform Firmware Solution Stack > +A UEFI firmware implementation using MinPlatformPkg is > constructed using the following pieces. > + > +| | > +|------------------------------------| > +| [EDK II](https://github.com/tianocore/edk2) > | > +| [Intel(r) FSP](https://github.com/IntelFsp/FSP) > | > +| [Minimum Platform > (`MinPlatformPkg`)](https://github.com/tianocore/edk2- > platforms/tree/devel- > MinPlatform/Platform/Intel/MinPlatformPkg) > | > +| [Board Support > (\OpenBoardPkg)](https://github.com/tianocore/edk > 2-platforms/tree/devel-MinPlatform/Platform/Intel) | > + > + > +## Board Support > +* The `KabylakeOpenBoardPkg` contains board > implementations for Kaby Lake systems. > +* The `PurleyOpenBoardPkg` contains board > implementations for Purley systems. > +* The `ClevoOpenBoardPkg` contains board > implementations for Clevo systems. > + > +## Board Package Organization > +The board package follows the standard EDK II package > structure with the following additional elements and > guidelines: > +* Only code usable across more than one board at the > root level. > +* Board-specific code in a directory. The directory > name should match that of the board supported. > +* Features not essential to achieve stage 5 or earlier > boots are maintained in a Features folder at the > appropriate > + level in the package hierarchy. > + > +Shared resources in the package root directory can > include interfaces described in header files, library > instances, > +firmware modules, binaries, etc. The UEFI firmware > implementation is built using the process described > below from the > +board-specific directory. > + > +A board package must implement the board APIs defined > in the MinPlatformPkg even if a "NULL" implementation > is used to > +return back to the minimum platform caller. >=20 > ## **Windows Build Instructions** >=20 > @@ -20,52 +85,87 @@ > - Add C:\Python27 to your path > - Other versions of 2.7 may also work fine. >=20 > -### Download the required component > +### Download the required components >=20 > -1. Create a new directory for an EDK II WORKSPACE. > +1. Create a new directory for the EDK II WORKSPACE. >=20 > 2. Download below repository to this WORKSPACE: >=20 > -edk2 repository > - ``git clone https://github.com/tianocore/edk2.git`` > +* edk2 repository > + * ``git clone > https://github.com/tianocore/edk2.git`` >=20 > -edk2-platforms repository > - ``git clone https://github.com/tianocore/edk2- > platforms.git -b devel-MinPlatform`` > +* edk2-platforms repository > + * ``git clone https://github.com/tianocore/edk2- > platforms.git -b devel-MinPlatform`` >=20 > -edk2-non-osi repository > - ``git clone https://github.com/tianocore/edk2-non- > osi.git -b devel-MinPlatform`` > +* edk2-non-osi repository > + * ``git clone https://github.com/tianocore/edk2-non- > osi.git -b devel-MinPlatform`` >=20 > -FSP repository > - ``git clone https://github.com/IntelFsp/FSP.git -b > Kabylake`` > +* FSP repository > + * ``git clone https://github.com/IntelFsp/FSP.git -b > Kabylake`` >=20 > ### Build >=20 > -For MinKabylake > -1. Open command window, goto the workspace dir, e.g. > c:\Kabylake. > +For KabylakeOpenBoardPkg > +1. Open command window, go to the workspace directory, > e.g. c:\Kabylake. > 2. Type "cd edk2- > platforms\Platform\Intel\KabylakeOpenBoardPkg\KabylakeR > vp3". > 3. Type "GitEdk2MinKabylake.bat" to setup GIT > environment. > -4. Type "prep" and make prebuild finish for debug > build, "prep r" for rlease build. > -5. Type "bld" to build kabylake BIOS image. > +4. Type "prep" and make prebuild finish for debug > build, "prep r" for release build. > +5. Type "bld" to build Kaby Lake reference platform > UEFI firmware image. >=20 > -For MinPurley > -1. Open command window, goto the workspace dir, e.g. > c:\Purley. > +For PurleyOpenBoardPkg > +1. Open command window, go to the workspace directory, > e.g. c:\Purley. > 2. Type "cd edk2- > platforms\Platform\Intel\PurleyOpenBoardPkg\BoardMtOlym > pus". > 3. Type "GitEdk2MinMtOlympus.bat" to setup GIT > environment. > -4. Type "bld" to build Purley BIOS image, "bld > release" for release build, "bld clean" to remove > intermediate files. > +4. Type "bld" to build Purley Mt Olympus board UEFI > firmware image, "bld release" for release build, "bld > clean" to > + remove intermediate files. >=20 > -The user can run FITC tool to build full image for > flash (BIOS + ME + DESC). The user can also burn the > BIOS image to highest part of flash region directly. > +The validated version of iasl compiler that can build > MinPurley is 20180629. Older version may generate ACPI > build > +errors. >=20 > -The validated version of iasl compiler that can build > MinPurley is 20180629. Older version may generate ACPI > build errors. > +For ClevoOpenBoardPkg > +1. Open command window, go to the workspace directory, > e.g. c:\Clevo. > +2. Type "cd edk2- > platforms\Platform\Intel\ClevoOpenBoardPkg\N1xxWU". > +3. Type "GitEdk2Clevo.bat" to setup GIT environment. > +4. Type "bld" to build Clevo UEFI firmware image, "bld > release" for release build, "bld clean" to remove > intermediate > +files. >=20 > -### Known limitations > +Users with access to the Intel proprietary FITC tool > and ME ingredients can build full images for flash > (BIOS + ME + > +DESC). >=20 > -For MinKabylake > -1. This firmware project has only been validated on > the Intel KabylakeRVP3 board. > -2. This firmware project has only been validated > booting to Microsoft Windows 10 x64 with AHCI mode and > Integrated Graphic Device. > -3. This firmware project has only been validated using > the Microsoft Visual Studio 2015 compiler. > +Users can also flash the UEFI firmware image to the > highest area of the flash region directly. >=20 > -For MinPurley > -1. This firmware project has only been validated on > the Microsoft MtOlympus board. > -2. This firmware project has only been validated > booting to Microsoft Windows Server 2016 with NVME on > M.2 slot. > -3. This firmware project has only been validated using > the Microsoft Visual Studio 2015 compiler. > +### **Known limitations** >=20 > +* All firmware projects can only build on Windows with > the validated configuration below. > + * Cross-platform build support is work-in-progress. > + > +**KabylakeOpenBoardPkg** > +1. This firmware project has only been tested on the > Intel KabylakeRvp3 board. > +2. This firmware project has only been tested booting > to Microsoft Windows 10 x64 with AHCI mode and > Integrated Graphic > + Device. > +3. This firmware project build has only been tested > using the Microsoft Visual Studio 2015 compiler. > + > +**PurleyOpenBoardPkg** > +1. This firmware project has only been tested on the > Microsoft MtOlympus board. > +2. This firmware project has only been tested booting > to Microsoft Windows Server 2016 with NVME on M.2 slot. > +3. This firmware project build has only been tested > using the Microsoft Visual Studio 2015 compiler. > + > +**ClevoOpenBoardPkg** > +1. Currently, support is only being added for the > N1xxWU series of boards. > +2. The firmware project build has only been tested > using the Microsoft Visual Studio 2015 compiler. > +3. The firmware project has not been tested on an > actual board, it *should not* be expected to boot. > +4. The firmware project applies to all Clevo supported > board configurations but is only being tested on System > 76 Galago > + Pro devices. > + > +### **Planned Activities** > +* Replace the batch build scripts with cross-platform > Python build scripts. > +* Publish a Minimum Platform specification to describe > the architecture and interfaces in more detail. > + > +### **Ideas** > +If you would like to help but are not sure where to > start some areas currently identified for improvement > include: > + * Adding board ports for more motherboards and > systems > + * Adding Clang support > + * Adding GCC support > + > +Please feel free to contact Michael Kubacki > (michael.a.kubacki at intel.com) and Isaac Oram > (isaac.w.oram at intel.com) > +if you would like to discuss contribution ideas. > -- > 2.16.2.windows.1