projects / mirror_edk2.git / blame
| Commit | Line | Data |
|---|---|---|
| a64b9449 CC |
1 | # FMMT\r |
| 2 | ## Overview\r | |
| 3 | This FMMT tool is the python implementation of the edk2 FMMT tool which locates at https://github.com/tianocore/edk2-staging/tree/FceFmmt.\r | |
| 4 | This implementation has the same usage as the edk2 FMMT, but it's more readable and relaiable.\r | |
| 5 | \r | |
| 6 | # FMMT User Guide\r | |
| 7 | \r | |
| 8 | #### Last updated April 28, 2022\r | |
| 9 | \r | |
| 10 | Important Changes and Updates:\r | |
| 11 | \r | |
| 12 | - Oct 13, 2021 Initial Draft of FMMT Python Tool\r | |
| 13 | - Apr 28, 2022 Optimize functions & Command line\r | |
| 14 | \r | |
| 15 | #### Note:\r | |
| 16 | \r | |
| 17 | - FMMT Python Tool keeps same function with origin FMMT C Tool. It is much easier to maintain and extend other functions.\r | |
| 18 | \r | |
| 19 | #### Known issue:\r | |
| 20 | \r | |
| 21 | - Currently, FMMT Python tool does not support PEIM rebase feature, this feature will be added in future update.\r | |
| 22 | \r | |
| 23 | # 1. Introduction\r | |
| 24 | \r | |
| 25 | ## 1.1 Overview\r | |
| 26 | \r | |
| 27 | The Firmware Device is a persistent physical repository that contains firmware code and/or data. The firmware code and/or data stored in Firmware Volumes. Detail layout of Firmware Volumes is described in ?Figure 1. The Firmware Volume Format?.\r | |
| 28 | \r | |
| 29 | \r | |
| 30 | \r | |
| 31 | ? Figure 1. The Firmware Volume Format\r | |
| 32 | \r | |
| 33 | In firmware development, binary file has its firmware layout following the Platform-Initialization Specification. Thus, operation on FV file / FFS file (Firmware File) is an efficient and convenient way for firmware function testing and developing. FMMT Python tool is used for firmware files operation.\r | |
| 34 | \r | |
| 35 | ## 1.2 Tool Capabilities\r | |
| 36 | \r | |
| 37 | The FMMT tool is capable of:\r | |
| 38 | \r | |
| 39 | - Parse a FD (Firmware Device) / FV (Firmware Volume) / FFS (Firmware Files)\r | |
| 40 | \r | |
| 41 | - Add a new FFS into a FV file (both included in a FD file or not)\r | |
| 42 | \r | |
| 43 | - Replace an FFS in a FV file with a new FFS file\r | |
| 44 | \r | |
| 45 | - Delete an FFS in a FV file (both included in a FD file or not)\r | |
| 46 | \r | |
| 47 | - Extract the FFS from a FV file (both included in a FD file or not)\r | |
| 48 | \r | |
| 49 | ## 1.3 References\r | |
| 50 | \r | |
| 51 | | Document |\r | |
| 52 | | ------------------------------------------------ |\r | |
| 53 | | UEFI Platform Initialization (PI) Specification |\r | |
| 54 | \r | |
| 55 | # 2. FMMT Python Tool Usage\r | |
| 56 | \r | |
| 57 | ## 2.1 Required Files\r | |
| 58 | \r | |
| 59 | ### 2.1.1 Independent use\r | |
| 60 | \r | |
| 61 | When independent use the FMMT Python Tool, the following files and settings are required:\r | |
| 62 | \r | |
| 63 | - GuidTool executable files used for Decompress/Compress Firmware data.\r | |
| 64 | \r | |
| 65 | - Environment variables path with GuidTool path setting.\r | |
| 66 | \r | |
| 67 | ### 2.1.2 Use with Build System\r | |
| 68 | \r | |
| 69 | When use the FMMT Python Tool with Build System:\r | |
| 70 | \r | |
| 71 | - If only use Edk2 based GuidTool, do not need other preparation.\r | |
| 72 | \r | |
| 73 | - If use other customized GuidTool, need prepare the config file with GuidTool info. The syntax for GuidTool definition shown as follow:\r | |
| 74 | \r | |
| 75 | ***ToolsGuid ShortName Command***\r | |
| 76 | \r | |
| 77 | -- Example: ***3d532050-5cda-4fd0-879e-0f7f630d5afb BROTLI BrotliCompress***\r | |
| 78 | \r | |
| 79 | ## 2.2 Syntax\r | |
| 80 | \r | |
| 81 | ### 2.2.1 Syntax for Parse file\r | |
| 82 | \r | |
| 83 | ***-v < Inputfile > < Outputfile > -l < LogFileType > -c < ConfigFilePath >***\r | |
| 84 | \r | |
| 85 | - Parse *Inputfile*, show its firmware layout with log file. *Outputfile* is optional, if inputs, the *Inputfile* will be encapsulated into *Outputfile* following the parsed firmware layout. *"-l LogFileType"* is optional, it decides the format of log file which saves Binary layout. Currently supports: json, txt. More formats will be added in the future. *"-c ConfigFilePath "* is optional, target FmmtConf.ini file can be selected with this parameter. If not provided, default FmmtConf.ini file will be used.\r | |
| 86 | - Ex: py -3 FMMT.py -v test.fd\r | |
| 87 | \r | |
| 88 | ### 2.2.2 Syntax for Add a new FFS\r | |
| 89 | \r | |
| 90 | ***-a < Inputfile > < TargetFvName/TargetFvGuid > < NewFfsFile > < Outputfile >***\r | |
| 91 | \r | |
| 92 | - Add the *NewFfsFile* into *Inputfile*. *TargetFvName/TargetFvGuid* (Name or Guid) is the TargetFv which *NewFfsFile* will be added into.\r | |
| 93 | - Ex: py -3 FMMT.py -a Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 NewAdd.ffs output.fd\r | |
| 94 | \r | |
| 95 | ### 2.2.3 Syntax for Delete an FFS\r | |
| 96 | \r | |
| 97 | ***-d < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < Outputfile >***\r | |
| 98 | \r | |
| 99 | - Delete the Ffs from *Inputfile*. TargetFfsName (Guid) is the TargetFfs which will be deleted. *TargetFvName/TargetFvGuid* is optional, which is the parent of TargetFfs*.*\r | |
| 100 | - Ex: py -3 FMMT.py -d Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei output.fd\r | |
| 101 | \r | |
| 102 | ### 2.2.4 Syntax for Replace an FFS\r | |
| 103 | \r | |
| 104 | ? ***-r < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < NewFfsFile > < Outputfile >***\r | |
| 105 | \r | |
| 106 | - Replace the Ffs with the NewFfsFile. TargetFfsName (Guid) is the TargetFfs which will be replaced. *TargetFvName/TargetFvGuid* is optional, which is the parent of TargetFfs*.*\r | |
| 107 | - Ex: py -3 FMMT.py -r Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei NewS3Resume2Pei.ffs output.fd\r | |
| 108 | \r | |
| 109 | ### 2.2.5 Syntax for Extract an FFS\r | |
| 110 | \r | |
| 111 | ***-e < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < Outputfile >***\r | |
| 112 | \r | |
| 113 | - Extract the Ffs from the Inputfile. TargetFfsName (Guid) is the TargetFfs which will be extracted. *TargetFvName/TargetFvGuid* is optional, which is the parent of TargetFfs*.*\r | |
| 114 | - Ex: py -3 FMMT.py -e Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei output.fd\r | |
| 115 | \r | |
| 116 | # 3. FMMT Python Tool Design\r | |
| 117 | \r | |
| 118 | FMMT Python Tool uses the NodeTree saves whole Firmware layout. Each Node have its Data field, which saves the FirmwareClass(FD/FV/FFS/SECTION/BINARY) Data. All the parse/add/delete/replace/extract operations are based on the NodeTree (adjusting the layout and data).\r | |
| 119 | \r | |
| 120 | ## 3.1 NodeTree\r | |
| 121 | \r | |
| 122 | A whole NodeTree saves all the Firmware info.\r | |
| 123 | \r | |
| 124 | - Parent & Child relationship figured out the Firmware layout.\r | |
| 125 | \r | |
| 126 | - Each Node have several fields. ?Data? field saves an FirmwareClass instance which contains all the data info of the info.\r | |
| 127 | \r | |
| 128 | ### 3.1.1 NodeTree Format\r | |
| 129 | \r | |
| 130 | The NodeTree will be created with parse function. When parse a file, a Root Node will be initialized firstly. The Data split and Tree construction process is described with an FD file shown as ?Figure 2. The NodeTree format?:\r | |
| 131 | \r | |
| 132 | - A Root Node is initialized.\r | |
| 133 | \r | |
| 134 | - Use the ?FV Signature? as FV key to split Whole FD Data. ?FV0?, ?FV1?, ?FV2?? Node created.\r | |
| 135 | \r | |
| 136 | - After FV level Node created, use the ?Ffs Data Size? as FFS key to split each FV Data. ?Ffs0?...Node created.\r | |
| 137 | \r | |
| 138 | - After FFS level Node created, use the ?Section Data Size? as Section key to split each Ffs Data. ?Section0?...Node created.\r | |
| 139 | \r | |
| 140 | - If some of Section includes other Sections, continue use the ?Section Data Size? as Section key to split each Section Data.\r | |
| 141 | \r | |
| 142 | - After all Node created, the whole NodeTree saves all the info. (Can be used in other functions or print the whole firmware layout into log file)\r | |
| 143 | \r | |
| 144 | \r | |
| 145 | \r | |
| 146 | ? Figure 2. The NodeTree format\r | |
| 147 | \r | |
| 148 | ### 3.1.2 Node Factory and Product\r | |
| 149 | \r | |
| 150 | As 3.1.1, Each Node is created by data split and recognition. To extend the NodeTree usage, Factory pattern is used in Node created process.\r | |
| 151 | \r | |
| 152 | Each Node have its Factory to create Product and use Product ParserData function to deal with the data.\r | |
| 153 | \r | |
| 154 | ## 3.2 GuidTool\r | |
| 155 | \r | |
| 156 | There are two ways to set the GuidTool. One from Config file, another from environment variables.\r | |
| 157 | \r | |
| 158 | Current GuidTool first check if has Config file.\r | |
| 159 | \r | |
| 160 | - If have, load the config GuidTool Information.\r | |
| 161 | \r | |
| 162 | - Else get from environment variables.\r | |
| 163 | \r | |
| 164 | ### 3.2.1 Get from Config file\r | |
| 165 | \r | |
| 166 | - Config file should in same folder with FMMT.py or the path in environment variables.\r | |
| 167 | \r | |
| 168 | - Content should follow the format:\r | |
| 169 | \r | |
| 170 | ***ToolsGuid ShortName Command***\r | |
| 171 | \r | |
| 172 | ### 3.2.2 Get from Environment Variables\r | |
| 173 | \r | |
| 174 | - The GuidTool Command used must be set in environment variables.\r | |
| 175 | \r | |
| 176 | ### 3.2.3 Edk2 Based GuidTool\r | |
| 177 | \r | |
| 178 | | ***Guid*** | ***ShortName*** | ***Command*** |\r | |
| 179 | | ------------------------------------------ | --------------- | --------------------- |\r | |
| 180 | | ***a31280ad-481e-41b6-95e8-127f4c984779*** | ***TIANO*** | ***TianoCompress*** |\r | |
| 181 | | ***ee4e5898-3914-4259-9d6e-dc7bd79403cf*** | ***LZMA*** | ***LzmaCompress*** |\r | |
| 182 | | ***fc1bcdb0-7d31-49aa-936a-a4600d9dd083*** | ***CRC32*** | ***GenCrc32*** |\r | |
| 183 | | ***d42ae6bd-1352-4bfb-909a-ca72a6eae889*** | ***LZMAF86*** | ***LzmaF86Compress*** |\r | |
| 184 | | ***3d532050-5cda-4fd0-879e-0f7f630d5afb*** | ***BROTLI*** | ***BrotliCompress*** |\r |