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

#Name\r
**_PatchFv.py_** - The python script that patches the firmware volumes (**FV**)\r
with in the flash device (**FD**) file post FSP build.\r
\r
#Synopsis\r
\r
```\r
PatchFv FvBuildDir [FvFileBaseNames:]FdFileBaseNameToPatch ["Offset, Value"]+\r
  | ["Offset, Value, @Comment"]+\r
  | ["Offset, Value, $Command"]+\r
  | ["Offset, Value, $Command, @Comment"]+\r
```\r
\r
#Description\r
The **_PatchFv.py_** tool allows the developer to fix up FD images to follow the\r
Intel FSP Architecture specification.  It also makes the FD image relocatable.\r
The tool is written in Python and uses Python 2.7 or later to run.\r
Consider using the tool in a build script.\r
\r
#FvBuildDir (Argument 1)\r
This is the first argument that **_PatchFv.py_** requires.  It is the build\r
directory for all firmware volumes created during the FSP build. The path must\r
be either an absolute path or a relevant path, relevant to the top level of the\r
FSP tree.\r
\r
####Example usage:\r
```\r
 Build\YouPlatformFspPkg\%BD_TARGET%_%VS_VERSION%%VS_X86%\FV\r
```\r
\r
The example used contains Windows batch script %VARIABLES%.\r
\r
#FvFileBaseNames (Argument 2: Optional Part 1)\r
The firmware volume file base names (**_FvFileBaseNames_**) are the independent\r
Fv?s that are to be patched within the FD. (0 or more in the form\r
**FVFILEBASENAME:**) The colon **:** is used for delimiting the single\r
argument and must be appended to the end of each (**_FvFileBaseNames_**).\r
\r
####Example usage:\r
```\r
STAGE1:STAGE2:MANIFEST:YOURPLATFORM\r
```\r
\r
In the example **STAGE1** is **STAGE1.Fv** in **YOURPLATFORM.fd**.\r
\r
# FdFileNameToPatch (Argument 2: Mandatory Part 2)\r
\r
Firmware device file name to patch (**_FdFileNameToPatch_**) is the base name of\r
the FD file that is to be patched. (1 only, in the form **YOURPLATFORM**)\r
\r
####Example usage:\r
```\r
STAGE1:STAGE2:MANIFEST:YOURPLATFORM\r
```\r
\r
In the example **YOURPLATFORM** is from **_YOURPLATFORM.fd_**\r
\r
#"Offset, Value[, Command][, Comment]" (Argument 3)\r
The **_Offset_** can be a positive or negative number and represents where the\r
**_Value_** to be patched is located within the FD. The **_Value_** is what\r
will be written at the given **_Offset_** in the FD. Constants may be used for\r
both offsets and values.  Also, this argument handles expressions for both\r
offsets and values using these operators:\r
\r
```\r
 = - * & | ~ ( ) [ ] { } < >\r
```\r
\r
The entire argument includes the quote marks like in the example argument below:\r
\r
```\r
0xFFFFFFC0, SomeCore:__EntryPoint - [0x000000F0],@SomeCore Entry\r
```\r
\r
###Constants:\r
 Hexadecimal (use **0x** as prefix) | Decimal\r
\r
####Examples:\r
\r
| **Positive Hex** | **Negative Hex** | **Positive Decimal** | **Negative Decimal** |\r
| ---------------: | ---------------: | -------------------: | -------------------: |\r
| 0x000000BC       | 0xFFFFFFA2       | 188                  | -94                  |\r
\r
```\r
ModuleName:FunctionName | ModuleName:GlobalVariableName\r
ModuleGuid:Offset\r
```\r
\r
###Operators:\r
\r
```\r
\r
  + Addition\r
  - Subtraction\r
  * Multiplication\r
  & Logical and\r
  | Logical or\r
  ~ Complement\r
  ( ) Evaluation control\r
  [ ] Get a DWord value at the specified offset expression from [expr]\r
  { } Convert an offset {expr} into an absolute address (FSP_BASE + expr)\r
  < > Convert absolute address <expr> into an image offset (expr & FSP_SIZE)\r
\r
```\r
\r
###Special Commands:\r
Special commands must use the **$** symbol as a prefix to the command itself.\r
There is only one command available at this time.\r
\r
```\r
$COPY ? Copy a binary block from source to destination.\r
```\r
\r
####Example:\r
\r
```\r
0x94, [PlatformInit:__gPcd_BinPatch_FvRecOffset] + 0x94, [0x98], $COPY, @Sync up 2nd FSP Header\r
```\r
\r
###Comments:\r
Comments are allowed in the **Offset, Value [, Comment]** argument. Comments\r
must use the **@** symbol as a prefix. The comment will output to the build\r
window upon successful completion of patching along with the offset and value data.\r
Commit	Line	Data
87c400e1 MG	1	#Name\r
	2	_PatchFv.py_ - The python script that patches the firmware volumes (FV)\r
	3	with in the flash device (FD) file post FSP build.\r
	4	\r
	5	#Synopsis\r
	6	\r
	7	```\r
	8	PatchFv FvBuildDir [FvFileBaseNames:]FdFileBaseNameToPatch ["Offset, Value"]+\r
	9	\| ["Offset, Value, @Comment"]+\r
	10	\| ["Offset, Value, $Command"]+\r
	11	\| ["Offset, Value, $Command, @Comment"]+\r
	12	```\r
	13	\r
	14	#Description\r
	15	The _PatchFv.py_ tool allows the developer to fix up FD images to follow the\r
	16	Intel FSP Architecture specification. It also makes the FD image relocatable.\r
	17	The tool is written in Python and uses Python 2.7 or later to run.\r
	18	Consider using the tool in a build script.\r
	19	\r
	20	#FvBuildDir (Argument 1)\r
	21	This is the first argument that _PatchFv.py_ requires. It is the build\r
	22	directory for all firmware volumes created during the FSP build. The path must\r
	23	be either an absolute path or a relevant path, relevant to the top level of the\r
	24	FSP tree.\r
	25	\r
	26	####Example usage:\r
	27	```\r
	28	Build\YouPlatformFspPkg\%BD_TARGET%_%VS_VERSION%%VS_X86%\FV\r
	29	```\r
	30	\r
	31	The example used contains Windows batch script %VARIABLES%.\r
	32	\r
f527942e	33	#FvFileBaseNames (Argument 2: Optional Part 1)\r
87c400e1 MG	34	The firmware volume file base names (_FvFileBaseNames_) are the independent\r
	35	Fv?s that are to be patched within the FD. (0 or more in the form\r
	36	FVFILEBASENAME:) The colon : is used for delimiting the single\r
	37	argument and must be appended to the end of each (_FvFileBaseNames_).\r
	38	\r
	39	####Example usage:\r
	40	```\r
	41	STAGE1:STAGE2:MANIFEST:YOURPLATFORM\r
	42	```\r
	43	\r
	44	In the example STAGE1 is STAGE1.Fv in YOURPLATFORM.fd.\r
	45	\r
	46	# FdFileNameToPatch (Argument 2: Mandatory Part 2)\r
	47	\r
	48	Firmware device file name to patch (_FdFileNameToPatch_) is the base name of\r
	49	the FD file that is to be patched. (1 only, in the form YOURPLATFORM)\r
	50	\r
	51	####Example usage:\r
	52	```\r
	53	STAGE1:STAGE2:MANIFEST:YOURPLATFORM\r
	54	```\r
	55	\r
	56	In the example YOURPLATFORM is from _YOURPLATFORM.fd_\r
	57	\r
	58	#"Offset, Value[, Command][, Comment]" (Argument 3)\r
	59	The _Offset_ can be a positive or negative number and represents where the\r
	60	_Value_ to be patched is located within the FD. The _Value_ is what\r
	61	will be written at the given _Offset_ in the FD. Constants may be used for\r
	62	both offsets and values. Also, this argument handles expressions for both\r
	63	offsets and values using these operators:\r
	64	\r
	65	```\r
	66	= - * & \| ~ ( ) [ ] { } < >\r
	67	```\r
	68	\r
	69	The entire argument includes the quote marks like in the example argument below:\r
	70	\r
	71	```\r
	72	0xFFFFFFC0, SomeCore:__EntryPoint - [0x000000F0],@SomeCore Entry\r
	73	```\r
	74	\r
	75	###Constants:\r
	76	Hexadecimal (use 0x as prefix) \| Decimal\r
	77	\r
	78	####Examples:\r
	79	\r
	80	\| Positive Hex \| Negative Hex \| Positive Decimal \| Negative Decimal \|\r
	81	\| ---------------: \| ---------------: \| -------------------: \| -------------------: \|\r
	82	\| 0x000000BC \| 0xFFFFFFA2 \| 188 \| -94 \|\r
	83	\r
	84	```\r
	85	ModuleName:FunctionName \| ModuleName:GlobalVariableName\r
	86	ModuleGuid:Offset\r
	87	```\r
	88	\r
	89	###Operators:\r
	90	\r
	91	```\r
	92	\r
	93	+ Addition\r
	94	- Subtraction\r
	95	* Multiplication\r
	96	& Logical and\r
	97	\| Logical or\r
98	~ Complement\r
99	( ) Evaluation control\r
100	[ ] Get a DWord value at the specified offset expression from [expr]\r
101	{ } Convert an offset {expr} into an absolute address (FSP_BASE + expr)\r
102	< > Convert absolute address <expr> into an image offset (expr & FSP_SIZE)\r
103	\r
104	```\r
105	\r
106	###Special Commands:\r
107	Special commands must use the $ symbol as a prefix to the command itself.\r
108	There is only one command available at this time.\r
109	\r
110	```\r
111	$COPY ? Copy a binary block from source to destination.\r
112	```\r
113	\r
114	####Example:\r
115	\r
116	```\r
117	0x94, [PlatformInit:__gPcd_BinPatch_FvRecOffset] + 0x94, [0x98], $COPY, @Sync up 2nd FSP Header\r
118	```\r
119	\r
120	###Comments:\r
121	Comments are allowed in the Offset, Value [, Comment] argument. Comments\r
122	must use the @ symbol as a prefix. The comment will output to the build\r
123	window upon successful completion of patching along with the offset and value data.\r