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