Re: [edk2-platforms/devel-MinPlatform][PATCH v3 1/1] ReadMe.md: Update Minimum Platform details

["Desimone, Nathaniel L" <nathaniel.l.desimone@intel.com>]

Reviewed-by: Nate DeSimone <nathaniel.l.desimone@intel.com>

On 2/4/19, 5:57 PM, "Kubacki, Michael A" <michael.a.kubacki@intel.com> wrote:

    Adds details on the EDK II Minimum Platform design for Intel
    platforms.
    
    * 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 <xxx>OpenBoardPkgs
    * Adds information for the ClevoOpenBoardPkg
    * Adds planned activities and ideas for the future
    
    Cc: Michael D Kinney <michael.d.kinney@intel.com>
    Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>
    Cc: Ankit Sinha <ankit.sinha@intel.com>
    Cc: Chasel Chiu <chasel.chiu@intel.com>
    Cc: Isaac W Oram <isaac.w.oram@intel.com>
    Cc: Liming Gao <liming.gao@intel.com>
    
    Contributed-under: TianoCore Contribution Agreement 1.0
    Signed-off-by: Michael Kubacki <michael.a.kubacki@intel.com>
    ---
     ReadMe.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++------------
     1 file changed, 132 insertions(+), 32 deletions(-)
    
    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**
     
    -## 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 \<xxx\>OpenBoardPkg where xxx refers to the
    +encompassing platform name for a particular platform generation. For example, the [`KabylakeOpenBoardPkg`](https://github.com/tianocore/edk2-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/edk2-platforms/blob/devel-MinPlatform/Platform/Intel/MinPlatformPkg/MinPlatformPkg.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 (\<xxx\>OpenBoardPkg)](https://github.com/tianocore/edk2-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.
     
     ## **Windows Build Instructions**
     
    @@ -20,52 +85,87 @@
       - Add C:\Python27 to your path
       - Other versions of 2.7 may also work fine.
     
    -### Download the required component
    +### Download the required components
     
    -1. Create a new directory for an EDK II WORKSPACE.
    +1. Create a new directory for the EDK II WORKSPACE.
     
     2. Download below repository to this WORKSPACE:
     
    -edk2 repository
    -	``git clone https://github.com/tianocore/edk2.git``
    +* edk2 repository
    +  * ``git clone https://github.com/tianocore/edk2.git``
     
    -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``
     
    -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``
     
    -FSP repository
    -	``git clone https://github.com/IntelFsp/FSP.git -b Kabylake``
    +* FSP repository
    +  * ``git clone https://github.com/IntelFsp/FSP.git -b Kabylake``
     
     ### Build
     
    -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\KabylakeRvp3".
     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.
     
    -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\BoardMtOlympus".
     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.
     
    -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.
     
    -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.
     
    -### Known limitations
    +Users with access to the Intel proprietary FITC tool and ME ingredients can build full images for flash  (BIOS + ME +
    +DESC).
     
    -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.
     
    -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**
     
    +* 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