IntelFsp2Pkg: Fix various typos

[mirror_edk2.git] / IntelFsp2Pkg / Tools / UserManuals / GenCfgOptUserManual.md

#Name\r
**GenCfgOpt.py** The python script that generates UPD text (**.txt**) files for\r
the compiler, header files for the UPD regions, and generates a Boot Settings\r
File (**BSF**), all from an EDK II Platform Description (**DSC**) file.\r
\r
#Synopsis\r
```\r
GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]\r
GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]\r
GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]\r
```\r
\r
#Description\r
**GenCfgOpt.py** is a script that generates configuration options from an\r
**EDK II Platform Description (DSC)** file. It has three functions.\r
\r
  1. It produces a **.txt** file that is used by the compiler that summarizes\r
     the UPD section in the DSC file.\r
  2. It generates header files for the UPD regions.\r
  3. It generates a **Boot Settings File (BSF)** that can be used by the\r
     **Binary Configuration Tool (BCT)** to provide a graphical user\r
     interface for manipulating settings in the UPD regions.\r
\r
The **GenCfgOpt.py** script generates important files that are vital parts of\r
your build process. The **UPDTXT** and **HEADER** use cases must be done before\r
the **'build'** command; the **GENBSF** use case may be done at any time.\r
\r
The following sections explain the three use cases.\r
\r
## 1. GenCfgOpt.py UPDTXT\r
The **UPDTXT** option creates a text file with all the UPD entries, offsets,\r
size in bytes, and values. **GenCfgOpt** reads this information from the\r
**[PcdsDynamicVpd.Upd]** section of the project's DSC file. The DSC file allows\r
you to specify offsets and sizes for each entry, opening up the possibility of\r
introducing gaps between entries. **GenCfgOpt** fills in these gaps with UPD\r
entries that have the generic names **UnusedUpdSpaceN** where N begins with 0\r
and increments. The command signature for **UPDTXT** is:\r
\r
```\r
GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]\r
```\r
\r
**PlatformDscFile** must be the location of the DSC file for the platform you're\r
building. **BuildFvDir** is the location where the binary will be stored. The\r
optional **TxtOutFile** is a name and location for the output of **GenCfgOpt**.\r
The default name and location is the ```<UPD_TOOL_GUID>.txt``` in the directory\r
specified by **BuildFvDir**. The macro ```UPD_TOOL_GUID``` must be defined in\r
the DSC file or in the optional Macros arguments. Each optional macro argument\r
must follow the form ```?D <MACRO_NAME>=<VALUE>```.\r
\r
**GenCfgOpt** checks to see if the UPD txt file has already been created and\r
will only re-create it if the DSC was modified after it was created.\r
\r
## 2. GenCfgOpt.py HEADER\r
The **HEADER** option creates header files in the build folder. Both header\r
files define the ```_UPD_DATA_REGION``` data structures in FspUpd.h, FsptUpd.h,\r
FspmUpd.h and FspsUpd.h. In these header files any undefined elements of\r
structures will be added as **ReservedUpdSpaceN** beginning with N=0. The\r
command signature for **HEADER** is\r
\r
```GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]```\r
\r
**PlatformDscFile** and **BuildFvDir** are described in the previous section.\r
The optional **InputHFile** is a header file that may contain data definitions\r
that are used by variables in the UPD regions. This header file must contain\r
the special keywords ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and\r
```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END``` in comments. Everything between\r
these two keywords will be included in the generated header file.\r
The mechanism to specify whether a variable appears as **ReservedUpdSpaceN** in\r
the FspUpd.h header file is in special commands that appear in the comments of\r
the DSC file. The special commands begin with ```!HDR```, for header. The\r
following table summarizes the two command options.\r
\r
### HEADER\r
Use the **HEADER** command to hide specific variables in the public header file.\r
In your project DSC file, use ```!HDR HEADER:{OFF}``` at the beginning of the\r
section you wish to hide and ```!HDR HEADER:{ON}``` at the end.\r
\r
### STRUCT\r
The **STRUCT** command allows you to specify a specific data type for a\r
variable. You can specify a pointer to a data struct, for example. You define\r
the data structure in the **InputHFile** between\r
```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and\r
```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END```.\r
\r
#####Example:\r
```!HDR STRUCT:{MY_DATA_STRUCT*}```\r
\r
You then define ```MY_DATA_STRUCT``` in **InputHFile**.\r
\r
### EMBED\r
The **EMBED** command allows you to put one or more UPD data into a specify data\r
structure. You can utilize it as a group of UPD for example. You must specify a\r
start and an end for the specify data structure.\r
\r
#####Example:\r
```\r
  !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:START}\r
  gTokenSpaceGuid.Upd1  | 0x0020 | 0x01 | 0x00\r
  gTokenSpaceGuid.Upd2  | 0x0021 | 0x01 | 0x00\r
  !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:END}\r
  gTokenSpaceGuid.UpdN  | 0x0022 | 0x01 | 0x00\r
```\r
\r
#####Result:\r
```\r
  typedef struct {\r
    /** Offset 0x0020\r
    **/\r
    UINT8                     Upd1;\r
    /** Offset 0x0021\r
    **/\r
    UINT8                     Upd2;\r
    /** Offset 0x0022\r
    **/\r
    UINT8                     UpdN;\r
  } MY_DATA_STRUCT;\r
\r
  typedef struct _UPD_DATA_REGION {\r
    ...\r
    /** Offset 0x0020\r
    **/\r
    MY_DATA_STRUCT    MyDataStruct;\r
    ...\r
  } UPD_DATA_REGION;\r
```\r
\r
## 3. GenCfgOpt .py GENBSF\r
The **GENBSF** option generates a BSF from the UPD entries in a package's DSC\r
file. It does this by parsing special commands found in the comments of the DSC\r
file. They roughly match the keywords that define the different sections of the\r
BSF.\r
\r
The command signature for **GENBSF** is\r
\r
```GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]```\r
\r
In this case, the **BsfOutFile** parameter is required; it should be the\r
relative path to where the BSF should be stored.\r
\r
Every BSF command in the DSC file begins with **!BSF** or **@Bsf**. The\r
following table summarizes the options that come after **!BSF** or **@Bsf**:\r
\r
# BSF Commands Description\r
###PAGES\r
**PAGES** maps abbreviations to friendly-text descriptions of the pages in a BSF.\r
\r
#####Example:\r
```!BSF PAGES:{PG1:?Page 1?, PG2:?Page 2?}``` or\r
\r
```@Bsf PAGES:{PG1:?Page 1?, PG2:?Page 2?}```\r
\r
###PAGE\r
This marks the beginning of a page. Use the abbreviation specified in **PAGES**\r
command.\r
\r
#####Example:\r
```!BSF PAGE:{PG1}``` or\r
\r
```@Bsf PAGE:{PG1}```\r
\r
All the entries that come after this command are assumed to be on that page,\r
until the next **PAGE** command\r
\r
###FIND\r
FIND maps to the BSF **Find** command. It will be placed in the **StructDef**\r
region of the BSF and should come at the beginning of the UPD sections of the\r
DSC, immediately before the signatures that mark the beginning of these\r
sections. The content should be the plain-text equivalent of the signature. The\r
signature is usually 8 characters.\r
\r
#####Example:\r
```!BSF FIND:{PROJSIG1}``` or\r
\r
```@Bsf FIND:{PROJSIG1}```\r
\r
###BLOCK\r
The BLOCK command maps to the **BeginInfoBlock** section of the BSF. There are\r
two elements: a version number and a plain-text description.\r
\r
#####Example:\r
```!BSF BLOCK:{NAME:"My platform name", VER:"0.1"}``` or\r
\r
```@Bsf BLOCK:{NAME:"My platform name", VER:"0.1"}```\r
\r
###NAME\r
**NAME** gives a plain-text for a variable. This is the text label that will\r
appear next to the control in **BCT**.\r
\r
#####Example:\r
```!BSF NAME:{Variable 0}``` or\r
\r
```@Bsf NAME:{Variable 0}```\r
\r
If the **!BSF NAME**  or **@Bsf NAME** command does not appear before an entry\r
in the UPD region of the DSC file, then that entry will not appear in the BSF.\r
\r
###TYPE\r
The **TYPE** command is used either by itself or with the **NAME** command. It\r
is usually used by itself when defining an **EditNum** field for the BSF. You\r
specify the type of data in the second parameter and the range of valid values\r
in the third.\r
\r
#####Example:\r
```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or\r
\r
```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```\r
\r
**TYPE** appears on the same line as the **NAME** command when using a combo-box.\r
\r
#####Example:\r
```!BSF NAME:{Variable 1} TYPE:{Combo}``` or\r
```@Bsf NAME:{Variable 1} TYPE:{Combo}```\r
\r
There is a special **None** type that puts the variable in the **StructDef**\r
region of the BSF, but doesn't put it in any **Page** section. This makes the\r
variable visible to BCT, but not to the end user.\r
\r
###HELP\r
The **HELP** command defines what will appear in the help text for each control\r
in BCT.\r
\r
#####Example:\r
```!BSF HELP:{Enable/disable LAN controller.}``` or\r
\r
```@Bsf HELP:{Enable/disable LAN controller.}```\r
\r
###OPTION\r
The **OPTION** command allows you to custom-define combo boxes and map integer\r
or hex values to friendly-text options.\r
\r
#####Example:\r
```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}```\r
\r
```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```\r
\r
or\r
\r
```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```\r
\r
```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```\r
\r
###FIELD\r
The **FIELD** command can be used to define a section of a consolidated PCD\r
such that the PCD will be displayed in several fields via BCT interface instead\r
of one long entry.\r
\r
#####Example:\r
```!BSF FIELD:{PcdDRAMSpeed:1}``` or\r
\r
```@Bsf FIELD:{PcdDRAMSpeed:1}```\r
\r
###ORDER\r
The **ORDER** command can be used to adjust the display order for the BSF items.\r
By default the order value for a BSF item is assigned to be the UPD item\r
```(Offset * 256)```. It can be overridden by declaring **ORDER** command using\r
format ORDER: ```{HexMajor.HexMinor}```. In this case the order value will be\r
```(HexMajor*256+HexMinor)```. The item order value will be used as the sort key\r
during the BSF item display.\r
\r
#####Example:\r
```!BSF ORDER:{0x0040.01}``` or\r
\r
```@Bsf ORDER:{0x0040.01}```\r
\r
For **OPTION** and **HELP** commands, it allows to split the contents into\r
multiple lines by adding multiple **OPTION** and **HELP** command lines. The\r
lines except for the very first line need to start with **+** in the content to\r
tell the tool to append this string to the previous one.\r
\r
For example, the statement\r
\r
```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```\r
\r
is equivalent to:\r
\r
```!BSF OPTION:{0x00:0 MB, 0x01:32 MB,}```\r
\r
```!BSF OPTION:{+ 0x02:64 MB}```\r
\r
or\r
\r
```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```\r
\r
is equivalent to:\r
\r
```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB,}```\r
\r
```@Bsf OPTION:{+ 0x02:64 MB}```\r
\r
The **NAME**, **OPTION**, **TYPE**, and **HELP** commands can all appear on the\r
same line following the **!BSF** or **@Bsf** keyword or they may appear on\r
separate lines to improve readability.\r
\r
There are four alternative ways to replace current BSF commands.\r
### 1. ```# @Prompt```\r
An alternative way replacing **NAME** gives a plain-text for a\r
variable. This is the text label that will appear next to the control in BCT.\r
\r
#####Example:\r
```# @Prompt Variable 0```\r
\r
The above example can replace the two methods as below.\r
\r
```!BSF NAME:{Variable 0}``` or\r
\r
```@Bsf NAME:{Variable 0}```\r
\r
If the ```# @Prompt``` command does not appear before an entry in the UPD region\r
of the DSC file, then that entry will not appear in the BSF.\r
\r
### 2. ```##```\r
An alternative way replacing **HELP** command defines what will appear in the\r
help text for each control in BCT.\r
\r
#####Example:\r
```## Enable/disable LAN controller.```\r
\r
The above example can replace the two methods as below.\r
\r
```!BSF HELP:{Enable/disable LAN controller.}``` or\r
\r
```@Bsf HELP:{Enable/disable LAN controller.}```\r
\r
### 3. ```# @ValidList```\r
An alternative way replacing **OPTION** command allows you to custom-define\r
combo boxes and map integer or hex values to friendly-text options.\r
\r
#####Example:\r
``` # @ValidList 0x80000003 | 0, 1, 2 | IDE, AHCI, RAID\r
                   Error Code | Options | Descriptions\r
```\r
\r
The above example can replace the two methods as below.\r
\r
```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}``` or\r
\r
```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```\r
\r
### 4. ```# @ValidRange```\r
An alternative way replace **EditNum** field for the BSF.\r
\r
#####Example:\r
```# @ValidRange 0x80000001 | 0x0 ? 0xFF\r
                    Error Code | Range\r
```\r
\r
The above example can replace the two methods as below.\r
\r
```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or\r
\r
```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```\r
\r