--- /dev/null
+#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
projects / mirror_edk2.git / commitdiff