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