Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 587 insertions, 0 deletions

diff --git a/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/FspDscBsf2YamlUserManual.md b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/FspDscBsf2YamlUserManual.md
new file mode 100644
index 00000000..e739ffc2
--- /dev/null
+++ b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/FspDscBsf2YamlUserManual.md
@@ -0,0 +1,39 @@
+#Name
+**FspDscBsf2Yaml.py** The python script that generates YAML file for
+the Boot Settings from an EDK II Platform Description (**DSC**) file
+or from a Boot Settings File (**BSF**). It is created to help
+transitioning FSP Updateable Product Data (**UPD**) file format to
+new standardized YAML format so that it can be configured through
+open source tools.
+
+#Synopsis
+```
+FspDscBsf2Yaml DscFile|BsfFile  YamlFile
+```
+
+#Description
+**FspDscBsf2Yaml.py** is a script that generates configuration options from an
+**EDK II Platform Description (DSC)** file or **a Boot Settings File (BSF)** file.
+
+It generates a **YAML file** that can be used by the **Config Editor** to provide
+a graphical user interface for manipulating settings in the UPD regions.
+
+The following sections explain the usage of this script.
+
+## 1. FspDscBsf2Yaml.py DscFile YamlFile
+
+The **DscFile** option is an input DSC file.
+
+The **YamlFile** option is an output YAML file.
+
+The script takes the FSP DSC file consisting BSF syntax and generates a YAML
+output file describing the boot settings.
+
+## 2. FspDscBsf2Yaml.py BsfFile YamlFile
+
+The **BsfFile** option is an input BSF file.
+
+The **YamlFile** option is an output YAML file.
+
+The script generates a YAML output file from a BSF file. The BSF file
+can be generated using GenCfgOpt tool.
diff --git a/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/GenCfgOptUserManual.md b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/GenCfgOptUserManual.md
new file mode 100644
index 00000000..53a42f94
--- /dev/null
+++ b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/GenCfgOptUserManual.md
@@ -0,0 +1,353 @@
+#Name
+**GenCfgOpt.py** The python script that generates UPD text (**.txt**) files for
+the compiler, header files for the UPD regions, and generates a Boot Settings
+File (**BSF**), all from an EDK II Platform Description (**DSC**) file.
+
+#Synopsis
+```
+GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]
+GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]
+GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]
+```
+
+#Description
+**GenCfgOpt.py** is a script that generates configuration options from an
+**EDK II Platform Description (DSC)** file. It has three functions.
+
+  1. It produces a **.txt** file that is used by the compiler that summarizes
+     the UPD section in the DSC file.
+  2. It generates header files for the UPD regions.
+  3. It generates a **Boot Settings File (BSF)** that can be used by the
+     **Binary Configuration Tool (BCT)** to provide a graphical user
+     interface for manipulating settings in the UPD regions.
+
+The **GenCfgOpt.py** script generates important files that are vital parts of
+your build process. The **UPDTXT** and **HEADER** use cases must be done before
+the **'build'** command; the **GENBSF** use case may be done at any time.
+
+The following sections explain the three use cases.
+
+## 1. GenCfgOpt.py UPDTXT
+The **UPDTXT** option creates a text file with all the UPD entries, offsets,
+size in bytes, and values. **GenCfgOpt** reads this information from the
+**[PcdsDynamicVpd.Upd]** section of the project's DSC file. The DSC file allows
+you to specify offsets and sizes for each entry, opening up the possibility of
+introducing gaps between entries. **GenCfgOpt** fills in these gaps with UPD
+entries that have the generic names **UnusedUpdSpaceN** where N begins with 0
+and increments. The command signature for **UPDTXT** is:
+
+```
+GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]
+```
+
+**PlatformDscFile** must be the location of the DSC file for the platform you're
+building. **BuildFvDir** is the location where the binary will be stored. The
+optional **TxtOutFile** is a name and location for the output of **GenCfgOpt**.
+The default name and location is the ```<UPD_TOOL_GUID>.txt``` in the directory
+specified by **BuildFvDir**. The macro ```UPD_TOOL_GUID``` must be defined in
+the DSC file or in the optional Macros arguments. Each optional macro argument
+must follow the form ```?D <MACRO_NAME>=<VALUE>```.
+
+**GenCfgOpt** checks to see if the UPD txt file has already been created and
+will only re-create it if the DSC was modified after it was created.
+
+## 2. GenCfgOpt.py HEADER
+The **HEADER** option creates header files in the build folder. Both header
+files define the ```_UPD_DATA_REGION``` data structures in FspUpd.h, FsptUpd.h,
+FspmUpd.h and FspsUpd.h. In these header files any undefined elements of
+structures will be added as **ReservedUpdSpaceN** beginning with N=0. The
+command signature for **HEADER** is
+
+```GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]```
+
+**PlatformDscFile** and **BuildFvDir** are described in the previous section.
+The optional **InputHFile** is a header file that may contain data definitions
+that are used by variables in the UPD regions. This header file must contain
+the special keywords ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and
+```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END``` in comments. Everything between
+these two keywords will be included in the generated header file.
+The mechanism to specify whether a variable appears as **ReservedUpdSpaceN** in
+the FspUpd.h header file is in special commands that appear in the comments of
+the DSC file. The special commands begin with ```!HDR```, for header. The
+following table summarizes the two command options.
+
+### HEADER
+Use the **HEADER** command to hide specific variables in the public header file.
+In your project DSC file, use ```!HDR HEADER:{OFF}``` at the beginning of the
+section you wish to hide and ```!HDR HEADER:{ON}``` at the end.
+
+### STRUCT
+The **STRUCT** command allows you to specify a specific data type for a
+variable. You can specify a pointer to a data struct, for example. You define
+the data structure in the **InputHFile** between
+```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and
+```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END```.
+
+#####Example:
+```!HDR STRUCT:{MY_DATA_STRUCT*}```
+
+You then define ```MY_DATA_STRUCT``` in **InputHFile**.
+
+### EMBED
+The **EMBED** command allows you to put one or more UPD data into a specify data
+structure. You can utilize it as a group of UPD for example. You must specify a
+start and an end for the specify data structure.
+
+#####Example:
+```
+  !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:START}
+  gTokenSpaceGuid.Upd1  | 0x0020 | 0x01 | 0x00
+  gTokenSpaceGuid.Upd2  | 0x0021 | 0x01 | 0x00
+  !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:END}
+  gTokenSpaceGuid.UpdN  | 0x0022 | 0x01 | 0x00
+```
+
+#####Result:
+```
+  typedef struct {
+    /** Offset 0x0020
+    **/
+    UINT8                     Upd1;
+    /** Offset 0x0021
+    **/
+    UINT8                     Upd2;
+    /** Offset 0x0022
+    **/
+    UINT8                     UpdN;
+  } MY_DATA_STRUCT;
+
+  typedef struct _UPD_DATA_REGION {
+    ...
+    /** Offset 0x0020
+    **/
+    MY_DATA_STRUCT    MyDataStruct;
+    ...
+  } UPD_DATA_REGION;
+```
+
+## 3. GenCfgOpt .py GENBSF
+The **GENBSF** option generates a BSF from the UPD entries in a package's DSC
+file. It does this by parsing special commands found in the comments of the DSC
+file. They roughly match the keywords that define the different sections of the
+BSF.
+
+The command signature for **GENBSF** is
+
+```GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]```
+
+In this case, the **BsfOutFile** parameter is required; it should be the
+relative path to where the BSF should be stored.
+
+Every BSF command in the DSC file begins with **!BSF** or **@Bsf**. The
+following table summarizes the options that come after **!BSF** or **@Bsf**:
+
+# BSF Commands Description
+###PAGES
+**PAGES** maps abbreviations to friendly-text descriptions of the pages in a BSF.
+
+#####Example:
+```!BSF PAGES:{PG1:?Page 1?, PG2:?Page 2?}``` or
+
+```@Bsf PAGES:{PG1:?Page 1?, PG2:?Page 2?}```
+
+###PAGE
+This marks the beginning of a page. Use the abbreviation specified in **PAGES**
+command.
+
+#####Example:
+```!BSF PAGE:{PG1}``` or
+
+```@Bsf PAGE:{PG1}```
+
+All the entries that come after this command are assumed to be on that page,
+until the next **PAGE** command
+
+###FIND
+FIND maps to the BSF **Find** command. It will be placed in the **StructDef**
+region of the BSF and should come at the beginning of the UPD sections of the
+DSC, immediately before the signatures that mark the beginning of these
+sections. The content should be the plain-text equivalent of the signature. The
+signature is usually 8 characters.
+
+#####Example:
+```!BSF FIND:{PROJSIG1}``` or
+
+```@Bsf FIND:{PROJSIG1}```
+
+###BLOCK
+The BLOCK command maps to the **BeginInfoBlock** section of the BSF. There are
+two elements: a version number and a plain-text description.
+
+#####Example:
+```!BSF BLOCK:{NAME:"My platform name", VER:"0.1"}``` or
+
+```@Bsf BLOCK:{NAME:"My platform name", VER:"0.1"}```
+
+###NAME
+**NAME** gives a plain-text for a variable. This is the text label that will
+appear next to the control in **BCT**.
+
+#####Example:
+```!BSF NAME:{Variable 0}``` or
+
+```@Bsf NAME:{Variable 0}```
+
+If the **!BSF NAME**  or **@Bsf NAME** command does not appear before an entry
+in the UPD region of the DSC file, then that entry will not appear in the BSF.
+
+###TYPE
+The **TYPE** command is used either by itself or with the **NAME** command. It
+is usually used by itself when defining an **EditNum** field for the BSF. You
+specify the type of data in the second parameter and the range of valid values
+in the third.
+
+#####Example:
+```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or
+
+```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```
+
+**TYPE** appears on the same line as the **NAME** command when using a combo-box.
+
+#####Example:
+```!BSF NAME:{Variable 1} TYPE:{Combo}``` or
+```@Bsf NAME:{Variable 1} TYPE:{Combo}```
+
+There is a special **None** type that puts the variable in the **StructDef**
+region of the BSF, but doesn't put it in any **Page** section. This makes the
+variable visible to BCT, but not to the end user.
+
+###HELP
+The **HELP** command defines what will appear in the help text for each control
+in BCT.
+
+#####Example:
+```!BSF HELP:{Enable/disable LAN controller.}``` or
+
+```@Bsf HELP:{Enable/disable LAN controller.}```
+
+###OPTION
+The **OPTION** command allows you to custom-define combo boxes and map integer
+or hex values to friendly-text options.
+
+#####Example:
+```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}```
+
+```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
+
+or
+
+```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```
+
+```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
+
+###FIELD
+The **FIELD** command can be used to define a section of a consolidated PCD
+such that the PCD will be displayed in several fields via BCT interface instead
+of one long entry.
+
+#####Example:
+```!BSF FIELD:{PcdDRAMSpeed:1}``` or
+
+```@Bsf FIELD:{PcdDRAMSpeed:1}```
+
+###ORDER
+The **ORDER** command can be used to adjust the display order for the BSF items.
+By default the order value for a BSF item is assigned to be the UPD item
+```(Offset * 256)```. It can be overridden by declaring **ORDER** command using
+format ORDER: ```{HexMajor.HexMinor}```. In this case the order value will be
+```(HexMajor*256+HexMinor)```. The item order value will be used as the sort key
+during the BSF item display.
+
+#####Example:
+```!BSF ORDER:{0x0040.01}``` or
+
+```@Bsf ORDER:{0x0040.01}```
+
+For **OPTION** and **HELP** commands, it allows to split the contents into
+multiple lines by adding multiple **OPTION** and **HELP** command lines. The
+lines except for the very first line need to start with **+** in the content to
+tell the tool to append this string to the previous one.
+
+For example, the statement
+
+```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
+
+is equivalent to:
+
+```!BSF OPTION:{0x00:0 MB, 0x01:32 MB,}```
+
+```!BSF OPTION:{+ 0x02:64 MB}```
+
+or
+
+```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
+
+is equivalent to:
+
+```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB,}```
+
+```@Bsf OPTION:{+ 0x02:64 MB}```
+
+The **NAME**, **OPTION**, **TYPE**, and **HELP** commands can all appear on the
+same line following the **!BSF** or **@Bsf** keyword or they may appear on
+separate lines to improve readability.
+
+There are four alternative ways to replace current BSF commands.
+### 1. ```# @Prompt```
+An alternative way replacing **NAME** gives a plain-text for a
+variable. This is the text label that will appear next to the control in BCT.
+
+#####Example:
+```# @Prompt Variable 0```
+
+The above example can replace the two methods as below.
+
+```!BSF NAME:{Variable 0}``` or
+
+```@Bsf NAME:{Variable 0}```
+
+If the ```# @Prompt``` command does not appear before an entry in the UPD region
+of the DSC file, then that entry will not appear in the BSF.
+
+### 2. ```##```
+An alternative way replacing **HELP** command defines what will appear in the
+help text for each control in BCT.
+
+#####Example:
+```## Enable/disable LAN controller.```
+
+The above example can replace the two methods as below.
+
+```!BSF HELP:{Enable/disable LAN controller.}``` or
+
+```@Bsf HELP:{Enable/disable LAN controller.}```
+
+### 3. ```# @ValidList```
+An alternative way replacing **OPTION** command allows you to custom-define
+combo boxes and map integer or hex values to friendly-text options.
+
+#####Example:
+``` # @ValidList 0x80000003 | 0, 1, 2 | IDE, AHCI, RAID
+                   Error Code | Options | Descriptions
+```
+
+The above example can replace the two methods as below.
+
+```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}``` or
+
+```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```
+
+### 4. ```# @ValidRange```
+An alternative way replace **EditNum** field for the BSF.
+
+#####Example:
+```# @ValidRange 0x80000001 | 0x0 ? 0xFF
+                    Error Code | Range
+```
+
+The above example can replace the two methods as below.
+
+```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or
+
+```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```
+
diff --git a/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/PatchFvUserManual.md b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/PatchFvUserManual.md
new file mode 100644
index 00000000..f0b10b18
--- /dev/null
+++ b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/PatchFvUserManual.md
@@ -0,0 +1,123 @@
+#Name
+**_PatchFv.py_** - The python script that patches the firmware volumes (**FV**)
+with in the flash device (**FD**) file post FSP build.
+
+#Synopsis
+
+```
+PatchFv FvBuildDir [FvFileBaseNames:]FdFileBaseNameToPatch ["Offset, Value"]+
+  | ["Offset, Value, @Comment"]+
+  | ["Offset, Value, $Command"]+
+  | ["Offset, Value, $Command, @Comment"]+
+```
+
+#Description
+The **_PatchFv.py_** tool allows the developer to fix up FD images to follow the
+Intel FSP Architecture specification.  It also makes the FD image relocatable.
+The tool is written in Python and uses Python 2.7 or later to run.
+Consider using the tool in a build script.
+
+#FvBuildDir (Argument 1)
+This is the first argument that **_PatchFv.py_** requires.  It is the build
+directory for all firmware volumes created during the FSP build. The path must
+be either an absolute path or a relevant path, relevant to the top level of the
+FSP tree.
+
+####Example usage:
+```
+ Build\YouPlatformFspPkg\%BD_TARGET%_%VS_VERSION%%VS_X86%\FV
+```
+
+The example used contains Windows batch script %VARIABLES%.
+
+#FvFileBaseNames (Argument 2: Optional Part 1)
+The firmware volume file base names (**_FvFileBaseNames_**) are the independent
+Fv?s that are to be patched within the FD. (0 or more in the form
+**FVFILEBASENAME:**) The colon **:** is used for delimiting the single
+argument and must be appended to the end of each (**_FvFileBaseNames_**).
+
+####Example usage:
+```
+STAGE1:STAGE2:MANIFEST:YOURPLATFORM
+```
+
+In the example **STAGE1** is **STAGE1.Fv** in **YOURPLATFORM.fd**.
+
+# FdFileNameToPatch (Argument 2: Mandatory Part 2)
+
+Firmware device file name to patch (**_FdFileNameToPatch_**) is the base name of
+the FD file that is to be patched. (1 only, in the form **YOURPLATFORM**)
+
+####Example usage:
+```
+STAGE1:STAGE2:MANIFEST:YOURPLATFORM
+```
+
+In the example **YOURPLATFORM** is from **_YOURPLATFORM.fd_**
+
+#"Offset, Value[, Command][, Comment]" (Argument 3)
+The **_Offset_** can be a positive or negative number and represents where the
+**_Value_** to be patched is located within the FD. The **_Value_** is what
+will be written at the given **_Offset_** in the FD. Constants may be used for
+both offsets and values.  Also, this argument handles expressions for both
+offsets and values using these operators:
+
+```
+ = - * & | ~ ( ) [ ] { } < >
+```
+
+The entire argument includes the quote marks like in the example argument below:
+
+```
+0xFFFFFFC0, SomeCore:__EntryPoint - [0x000000F0],@SomeCore Entry
+```
+
+###Constants:
+ Hexadecimal (use **0x** as prefix) | Decimal
+
+####Examples:
+
+| **Positive Hex** | **Negative Hex** | **Positive Decimal** | **Negative Decimal** |
+| ---------------: | ---------------: | -------------------: | -------------------: |
+| 0x000000BC       | 0xFFFFFFA2       | 188                  | -94                  |
+
+```
+ModuleName:FunctionName | ModuleName:GlobalVariableName
+ModuleGuid:Offset
+```
+
+###Operators:
+
+```
+
+  + Addition
+  - Subtraction
+  * Multiplication
+  & Logical and
+  | Logical or
+  ~ Complement
+  ( ) Evaluation control
+  [ ] Get a DWord value at the specified offset expression from [expr]
+  { } Convert an offset {expr} into an absolute address (FSP_BASE + expr)
+  < > Convert absolute address <expr> into an image offset (expr & FSP_SIZE)
+
+```
+
+###Special Commands:
+Special commands must use the **$** symbol as a prefix to the command itself.
+There is only one command available at this time.
+
+```
+$COPY ? Copy a binary block from source to destination.
+```
+
+####Example:
+
+```
+0x94, [PlatformInit:__gPcd_BinPatch_FvRecOffset] + 0x94, [0x98], $COPY, @Sync up 2nd FSP Header
+```
+
+###Comments:
+Comments are allowed in the **Offset, Value [, Comment]** argument. Comments
+must use the **@** symbol as a prefix. The comment will output to the build
+window upon successful completion of patching along with the offset and value data.
diff --git a/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/SplitFspBinUserManual.md b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/SplitFspBinUserManual.md
new file mode 100644
index 00000000..ebaa6830
--- /dev/null
+++ b/src/VBox/Devices/EFI/Firmware/IntelFsp2Pkg/Tools/UserManuals/SplitFspBinUserManual.md
@@ -0,0 +1,72 @@
+# SplitFspBin.py is a python script to support some operations on Intel FSP 1.x/2.x image.
+
+It supports:
+
+- Split Intel FSP 2.x image into individual FSP-T/M/S/O component
+
+- Rebase Intel FSP 1.x/2.x components to different base addresses
+
+- Generate Intel FSP 1.x/2.x C header file
+
+- Display Intel FSP 1.x/2.x information header for each FSP component
+
+## Split Intel FSP 2.x image
+
+FSP 1.x image is not supported by split command.
+To split individual FSP component in Intel FSP 2.x image, the following
+command can be used:
+
+   **python SplitFspBin.py split [-h] -f FSPBINARY [-o OUTPUTDIR] [-n NAMETEMPLATE]**
+
+For example:
+
+   `python SplitFspBin.py split -f FSP.bin`
+
+   It will create FSP_T.bin, FSP_M.bin and FSP_S.bin in current directory.
+
+## Rebase Intel FSP 1.x/2.x components
+
+To rebase one or multiple FSP components in Intel FSP 1.x/2.x image, the following
+command can be used:
+
+   **python SplitFspBin.py rebase [-h] -f FSPBINARY -c {t,m,s,o} [{t,m,s,o} ...] -b FSPBASE [FSPBASE ...] [-o OUTPUTDIR] [-n OUTPUTFILE]**
+
+For example:
+
+   `python SplitFspBin.py rebase -f FSP.bin -c t -b 0xFFF00000 -n FSP_new.bin`
+
+   It will rebase FSP-T component inside FSP.bin to new base 0xFFF00000 and save the
+   rebased Intel FSP 2.x image into file FSP_new.bin.
+   For FSP 1.x image there is only one component in binary so above command also
+   works for FSP 1.x image.
+
+   `python SplitFspBin.py rebase -f FSP.bin -c t m -b 0xFFF00000 0xFEF80000 -n FSP_new.bin`
+
+   It will rebase FSP-T and FSP-M components inside FSP.bin to new base 0xFFF00000
+   and 0xFEF80000 respectively, and save the rebased Intel FSP 2.x image into file
+   FSP_new.bin file.
+
+## Generate Intel FSP 1.x/2.x C header file
+
+To generate Intel FSP 1.x/2.x C header file, the following command can be used:
+
+   **Python SplitFspBin.py genhdr [-h] -f FSPBINARY [-o OUTPUTDIR] [-n HFILENAME]**
+
+For example:
+
+   `python SplitFspBin.py genhdr -f FSP.bin -n FSP.h`
+
+   It will create the C header file FSP.h containing the image ID, revision, offset
+   and size for each individual FSP component.
+
+## Display Intel FSP 1.x/2.x information header
+
+To display Intel FSP 1.x/2.x information headers, the following command can be used:
+
+   **Python SplitFspBin.py info [-h] -f FSPBINARY**
+
+For example:
+
+   `python SplitFspBin.py info -f FSP.bin`
+
+   It will print out the FSP information header for each FSP component.