IntelFsp2Pkg/Tools/UserManuals/GenCfgOptUserManual.md

   1 #Name
   2 **GenCfgOpt.py** The python script that generates UPD text (**.txt**) files for
   3 the compiler, header files for the UPD regions, and generates a Boot Settings
   4 File (**BSF**), all from an EDK II Platform Description (**DSC**) file.
   5
   6 #Synopsis
   7 ```
   8 GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]
   9 GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]
  10 GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]
  11 ```
  12
  13 #Description
  14 **GenCfgOpt.py** is a script that generates configuration options from an
  15 **EDK II Platform Description (DSC)** file. It has three functions.
  16
  17   1. It produces a **.txt** file that is used by the compiler that summarizes
  18      the UPD section in the DSC file.
  19   2. It generates header files for the UPD regions.
  20   3. It generates a **Boot Settings File (BSF)** that can be used by the
  21      **Binary Configuration Tool (BCT)** to provide a graphical user
  22      interface for manipulating settings in the UPD regions.
  23
  24 The **GenCfgOpt.py** script generates important files that are vital parts of
  25 your build process. The **UPDTXT** and **HEADER** use cases must be done before
  26 the **'build'** command; the **GENBSF** use case may be done at any time.
  27
  28 The following sections explain the three use cases.
  29
  30 ## 1. GenCfgOpt.py UPDTXT
  31 The **UPDTXT** option creates a text file with all the UPD entries, offsets,
  32 size in bytes, and values. **GenCfgOpt** reads this information from the
  33 **[PcdsDynamicVpd.Upd]** section of the project's DSC file. The DSC file allows
  34 you to specify offsets and sizes for each entry, opening up the possibility of
  35 introducing gaps between entries. **GenCfgOpt** fills in these gaps with UPD
  36 entries that have the generic names **UnusedUpdSpaceN** where N begins with 0
  37 and increments. The command signature for **UPDTXT** is:
  38
  39 ```
  40 GenCfgOpt UPDTXT PlatformDscFile BuildFvDir [TxtOutFile] [-D Macros]
  41 ```
  42
  43 **PlatformDscFile** must be the location of the DSC file for the platform you're
  44 building. **BuildFvDir** is the location where the binary will be stored. The
  45 optional **TxtOutFile** is a name and location for the output of **GenCfgOpt**.
  46 The default name and location is the ```<UPD_TOOL_GUID>.txt``` in the directory
  47 specified by **BuildFvDir**. The macro ```UPD_TOOL_GUID``` must be defined in
  48 the DSC file or in the optional Macros arguments. Each optional macro argument
  49 must follow the form ```?D <MACRO_NAME>=<VALUE>```.
  50
  51 **GenCfgOpt** checks to see if the UPD txt file has already been created and
  52 will only re-create it if the DSC was modified after it was created.
  53
  54 ## 2. GenCfgOpt.py HEADER
  55 The **HEADER** option creates header files in the build folder. Both header
  56 files define the ```_UPD_DATA_REGION``` data structures in FspUpd.h, FsptUpd.h,
  57 FspmUpd.h and FspsUpd.h. In these header files any undefined elements of
  58 structures will be added as **ReservedUpdSpaceN** beginning with N=0. The
  59 command signature for **HEADER** is
  60
  61 ```GenCfgOpt HEADER PlatformDscFile BuildFvDir [InputHFile] [-D Macros]```
  62
  63 **PlatformDscFile** and **BuildFvDir** are described in the previous section.
  64 The optional **InputHFile** is a header file that may contain data definitions
  65 that are used by variables in the UPD regions. This header file must contain
  66 the special keywords ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and
  67 ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END``` in comments. Everything between
  68 these two keywords will be included in the generated header file.
  69 The mechanism to specify whether a variable appears as **ReservedUpdSpaceN** in
  70 the FspUpd.h header file is in special commands that appear in the comments of
  71 the DSC file. The special commands begin with ```!HDR```, for header. The
  72 following table summarizes the two command options.
  73
  74 ### HEADER
  75 Use the **HEADER** command to hide specific variables in the public header file.
  76 In your project DSC file, use ```!HDR HEADER:{OFF}``` at the beginning of the
  77 section you wish to hide and ```!HDR HEADER:{ON}``` at the end.
  78
  79 ### STRUCT
  80 The **STRUCT** command allows you to specify a specific data type for a
  81 variable. You can specify a pointer to a data struct, for example. You define
  82 the data structure in the **InputHFile** between
  83 ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_BEGIN``` and
  84 ```!EXPORT EXTERNAL_BOOTLOADER_STRUCT_END```.
  85
  86 #####Example:
  87 ```!HDR STRUCT:{MY_DATA_STRUCT*}```
  88
  89 You then define ```MY_DATA_STRUCT``` in **InputHFile**.
  90
  91 ### EMBED
  92 The **EMBED** command allows you to put one or more UPD data into a specify data
  93 structure. You can utilize it as a group of UPD for example. You must specify a
  94 start and an end for the specify data structure.
  95
  96 #####Example:
  97 ```
  98   !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:START}
  99   gTokenSpaceGuid.Upd1  | 0x0020 | 0x01 | 0x00
 100   gTokenSpaceGuid.Upd2  | 0x0021 | 0x01 | 0x00
 101   !HDR EMBED:{MY_DATA_STRUCT:MyDataStructure:END}
 102   gTokenSpaceGuid.UpdN  | 0x0022 | 0x01 | 0x00
 103 ```
 104
 105 #####Result:
 106 ```
 107   typedef struct {
 108     /** Offset 0x0020
 109     **/
 110     UINT8                     Upd1;
 111     /** Offset 0x0021
 112     **/
 113     UINT8                     Upd2;
 114     /** Offset 0x0022
 115     **/
 116     UINT8                     UpdN;
 117   } MY_DATA_STRUCT;
 118
 119   typedef struct _UPD_DATA_REGION {
 120     ...
 121     /** Offset 0x0020
 122     **/
 123     MY_DATA_STRUCT    MyDataStruct;
 124     ...
 125   } UPD_DATA_REGION;
 126 ```
 127
 128 ## 3. GenCfgOpt .py GENBSF
 129 The **GENBSF** option generates a BSF from the UPD entries in a package's DSC
 130 file. It does this by parsing special commands found in the comments of the DSC
 131 file. They roughly match the keywords that define the different sections of the
 132 BSF.
 133
 134 The command signature for **GENBSF** is
 135
 136 ```GenCfgOpt GENBSF PlatformDscFile BuildFvDir BsfOutFile [-D Macros]```
 137
 138 In this case, the **BsfOutFile** parameter is required; it should be the
 139 relative path to where the BSF should be stored.
 140
 141 Every BSF command in the DSC file begins with **!BSF** or **@Bsf**. The
 142 following table summarizes the options that come after **!BSF** or **@Bsf**:
 143
 144 # BSF Commands Description
 145 ###PAGES
 146 **PAGES** maps abbreviations to friendly-text descriptions of the pages in a BSF.
 147
 148 #####Example:
 149 ```!BSF PAGES:{PG1:?Page 1?, PG2:?Page 2?}``` or
 150
 151 ```@Bsf PAGES:{PG1:?Page 1?, PG2:?Page 2?}```
 152
 153 ###PAGE
 154 This marks the beginning of a page. Use the abbreviation specified in **PAGES**
 155 command.
 156
 157 #####Example:
 158 ```!BSF PAGE:{PG1}``` or
 159
 160 ```@Bsf PAGE:{PG1}```
 161
 162 All the entries that come after this command are assumed to be on that page,
 163 until the next **PAGE** command
 164
 165 ###FIND
 166 FIND maps to the BSF **Find** command. It will be placed in the **StructDef**
 167 region of the BSF and should come at the beginning of the UPD sections of the
 168 DSC, immediately before the signatures that mark the beginning of these
 169 sections. The content should be the plain-text equivalent of the signature. The
 170 signature is usually 8 characters.
 171
 172 #####Example:
 173 ```!BSF FIND:{PROJSIG1}``` or
 174
 175 ```@Bsf FIND:{PROJSIG1}```
 176
 177 ###BLOCK
 178 The BLOCK command maps to the **BeginInfoBlock** section of the BSF. There are
 179 two elements: a version number and a plain-text description.
 180
 181 #####Example:
 182 ```!BSF BLOCK:{NAME:"My platform name", VER:"0.1"}``` or
 183
 184 ```@Bsf BLOCK:{NAME:"My platform name", VER:"0.1"}```
 185
 186 ###NAME
 187 **NAME** gives a plain-text for a variable. This is the text label that will
 188 appear next to the control in **BCT**.
 189
 190 #####Example:
 191 ```!BSF NAME:{Variable 0}``` or
 192
 193 ```@Bsf NAME:{Variable 0}```
 194
 195 If the **!BSF NAME**  or **@Bsf NAME** command does not appear before an entry
 196 in the UPD region of the DSC file, then that entry will not appear in the BSF.
 197
 198 ###TYPE
 199 The **TYPE** command is used either by itself or with the **NAME** command. It
 200 is usually used by itself when defining an **EditNum** field for the BSF. You
 201 specify the type of data in the second parameter and the range of valid values
 202 in the third.
 203
 204 #####Example:
 205 ```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or
 206
 207 ```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```
 208
 209 **TYPE** appears on the same line as the **NAME** command when using a combo-box.
 210
 211 #####Example:
 212 ```!BSF NAME:{Variable 1} TYPE:{Combo}``` or
 213 ```@Bsf NAME:{Variable 1} TYPE:{Combo}```
 214
 215 There is a special **None** type that puts the variable in the **StructDef**
 216 region of the BSF, but doesn't put it in any **Page** section. This makes the
 217 variable visible to BCT, but not to the end user.
 218
 219 ###HELP
 220 The **HELP** command defines what will appear in the help text for each control
 221 in BCT.
 222
 223 #####Example:
 224 ```!BSF HELP:{Enable/disable LAN controller.}``` or
 225
 226 ```@Bsf HELP:{Enable/disable LAN controller.}```
 227
 228 ###OPTION
 229 The **OPTION** command allows you to custom-define combo boxes and map integer
 230 or hex values to friendly-text options.
 231
 232 #####Example:
 233 ```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}```
 234
 235 ```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
 236
 237 or
 238
 239 ```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```
 240
 241 ```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
 242
 243 ###FIELD
 244 The **FIELD** command can be used to define a section of a consolidated PCD
 245 such that the PCD will be displayed in several fields via BCT interface instead
 246 of one long entry.
 247
 248 #####Example:
 249 ```!BSF FIELD:{PcdDRAMSpeed:1}``` or
 250
 251 ```@Bsf FIELD:{PcdDRAMSpeed:1}```
 252
 253 ###ORDER
 254 The **ORDER** command can be used to adjust the display order for the BSF items.
 255 By default the order value for a BSF item is assigned to be the UPD item
 256 ```(Offset * 256)```. It can be overridden by declaring **ORDER** command using
 257 format ORDER: ```{HexMajor.HexMinor}```. In this case the order value will be
 258 ```(HexMajor*256+HexMinor)```. The item order value will be used as the sort key
 259 during the BSF item display.
 260
 261 #####Example:
 262 ```!BSF ORDER:{0x0040.01}``` or
 263
 264 ```@Bsf ORDER:{0x0040.01}```
 265
 266 For **OPTION** and **HELP** commands, it allows to split the contents into
 267 multiple lines by adding multiple **OPTION** and **HELP** command lines. The
 268 lines except for the very first line need to start with **+** in the content to
 269 tell the tool to append this string to the previous one.
 270
 271 For example, the statement
 272
 273 ```!BSF OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
 274
 275 is equivalent to:
 276
 277 ```!BSF OPTION:{0x00:0 MB, 0x01:32 MB,}```
 278
 279 ```!BSF OPTION:{+ 0x02:64 MB}```
 280
 281 or
 282
 283 ```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB, 0x02:64 MB}```
 284
 285 is equivalent to:
 286
 287 ```@Bsf OPTION:{0x00:0 MB, 0x01:32 MB,}```
 288
 289 ```@Bsf OPTION:{+ 0x02:64 MB}```
 290
 291 The **NAME**, **OPTION**, **TYPE**, and **HELP** commands can all appear on the
 292 same line following the **!BSF** or **@Bsf** keyword or they may appear on
 293 separate lines to improve readability.
 294
 295 There are four alternative ways to replace current BSF commands.
 296 ### 1. ```# @Prompt```
 297 An alternative way replacing **NAME** gives a plain-text for a
 298 variable. This is the text label that will appear next to the control in BCT.
 299
 300 #####Example:
 301 ```# @Prompt Variable 0```
 302
 303 The above example can replace the two methods as below.
 304
 305 ```!BSF NAME:{Variable 0}``` or
 306
 307 ```@Bsf NAME:{Variable 0}```
 308
 309 If the ```# @Prompt``` command does not appear before an entry in the UPD region
 310 of the DSC file, then that entry will not appear in the BSF.
 311
 312 ### 2. ```##```
 313 An alternative way replacing **HELP** command defines what will appear in the
 314 help text for each control in BCT.
 315
 316 #####Example:
 317 ```## Enable/disable LAN controller.```
 318
 319 The above example can replace the two methods as below.
 320
 321 ```!BSF HELP:{Enable/disable LAN controller.}``` or
 322
 323 ```@Bsf HELP:{Enable/disable LAN controller.}```
 324
 325 ### 3. ```# @ValidList```
 326 An alternative way replacing **OPTION** command allows you to custom-define
 327 combo boxes and map integer or hex values to friendly-text options.
 328
 329 #####Example:
 330 ``` # @ValidList 0x80000003 | 0, 1, 2 | IDE, AHCI, RAID
 331                    Error Code | Options | Descriptions
 332 ```
 333
 334 The above example can replace the two methods as below.
 335
 336 ```!BSF OPTION:{0:IDE, 1:AHCI, 2:RAID}``` or
 337
 338 ```@Bsf OPTION:{0:IDE, 1:AHCI, 2:RAID}```
 339
 340 ### 4. ```# @ValidRange```
 341 An alternative way replace **EditNum** field for the BSF.
 342
 343 #####Example:
 344 ```# @ValidRange 0x80000001 | 0x0 ? 0xFF
 345                     Error Code | Range
 346 ```
 347
 348 The above example can replace the two methods as below.
 349
 350 ```!BSF TYPE:{EditNum, HEX, (0x00,0xFF)}``` or
 351
 352 ```@Bsf TYPE:{EditNum, HEX, (0x00,0xFF)}```
 353