mirror of https://github.com/acidanthera/audk.git
184 lines
8.0 KiB
Markdown
184 lines
8.0 KiB
Markdown
# FMMT
|
|
## Overview
|
|
This FMMT tool is the python implementation of the edk2 FMMT tool which locates at https://github.com/tianocore/edk2-staging/tree/FceFmmt.
|
|
This implementation has the same usage as the edk2 FMMT, but it's more readable and relaiable.
|
|
|
|
# FMMT User Guide
|
|
|
|
#### Last updated April 28, 2022
|
|
|
|
Important Changes and Updates:
|
|
|
|
- Oct 13, 2021 Initial Draft of FMMT Python Tool
|
|
- Apr 28, 2022 Optimize functions & Command line
|
|
|
|
#### Note:
|
|
|
|
- FMMT Python Tool keeps same function with origin FMMT C Tool. It is much easier to maintain and extend other functions.
|
|
|
|
#### Known issue:
|
|
|
|
- Currently, FMMT Python tool does not support PEIM rebase feature, this feature will be added in future update.
|
|
|
|
# 1. Introduction
|
|
|
|
## 1.1 Overview
|
|
|
|
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?.
|
|
|
|
|
|
|
|
? Figure 1. The Firmware Volume Format
|
|
|
|
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.
|
|
|
|
## 1.2 Tool Capabilities
|
|
|
|
The FMMT tool is capable of:
|
|
|
|
- Parse a FD (Firmware Device) / FV (Firmware Volume) / FFS (Firmware Files)
|
|
|
|
- Add a new FFS into a FV file (both included in a FD file or not)
|
|
|
|
- Replace an FFS in a FV file with a new FFS file
|
|
|
|
- Delete an FFS in a FV file (both included in a FD file or not)
|
|
|
|
- Extract the FFS from a FV file (both included in a FD file or not)
|
|
|
|
## 1.3 References
|
|
|
|
| Document |
|
|
| ------------------------------------------------ |
|
|
| UEFI Platform Initialization (PI) Specification |
|
|
|
|
# 2. FMMT Python Tool Usage
|
|
|
|
## 2.1 Required Files
|
|
|
|
### 2.1.1 Independent use
|
|
|
|
When independent use the FMMT Python Tool, the following files and settings are required:
|
|
|
|
- GuidTool executable files used for Decompress/Compress Firmware data.
|
|
|
|
- Environment variables path with GuidTool path setting.
|
|
|
|
### 2.1.2 Use with Build System
|
|
|
|
When use the FMMT Python Tool with Build System:
|
|
|
|
- If only use Edk2 based GuidTool, do not need other preparation.
|
|
|
|
- If use other customized GuidTool, need prepare the config file with GuidTool info. The syntax for GuidTool definition shown as follow:
|
|
|
|
***ToolsGuid ShortName Command***
|
|
|
|
-- Example: ***3d532050-5cda-4fd0-879e-0f7f630d5afb BROTLI BrotliCompress***
|
|
|
|
## 2.2 Syntax
|
|
|
|
### 2.2.1 Syntax for Parse file
|
|
|
|
***-v < Inputfile > < Outputfile > -l < LogFileType > -c < ConfigFilePath >***
|
|
|
|
- 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.
|
|
- Ex: py -3 FMMT.py -v test.fd
|
|
|
|
### 2.2.2 Syntax for Add a new FFS
|
|
|
|
***-a < Inputfile > < TargetFvName/TargetFvGuid > < NewFfsFile > < Outputfile >***
|
|
|
|
- Add the *NewFfsFile* into *Inputfile*. *TargetFvName/TargetFvGuid* (Name or Guid) is the TargetFv which *NewFfsFile* will be added into.
|
|
- Ex: py -3 FMMT.py -a Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 NewAdd.ffs output.fd
|
|
|
|
### 2.2.3 Syntax for Delete an FFS
|
|
|
|
***-d < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < Outputfile >***
|
|
|
|
- Delete the Ffs from *Inputfile*. TargetFfsName (Guid) is the TargetFfs which will be deleted. *TargetFvName/TargetFvGuid* is optional, which is the parent of TargetFfs*.*
|
|
- Ex: py -3 FMMT.py -d Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei output.fd
|
|
|
|
### 2.2.4 Syntax for Replace an FFS
|
|
|
|
? ***-r < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < NewFfsFile > < Outputfile >***
|
|
|
|
- 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*.*
|
|
- Ex: py -3 FMMT.py -r Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei NewS3Resume2Pei.ffs output.fd
|
|
|
|
### 2.2.5 Syntax for Extract an FFS
|
|
|
|
***-e < Inputfile > < TargetFvName/TargetFvGuid > < TargetFfsName > < Outputfile >***
|
|
|
|
- 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*.*
|
|
- Ex: py -3 FMMT.py -e Ovmf.fd 6938079b-b503-4e3d-9d24-b28337a25806 S3Resume2Pei output.fd
|
|
|
|
# 3. FMMT Python Tool Design
|
|
|
|
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).
|
|
|
|
## 3.1 NodeTree
|
|
|
|
A whole NodeTree saves all the Firmware info.
|
|
|
|
- Parent & Child relationship figured out the Firmware layout.
|
|
|
|
- Each Node have several fields. ?Data? field saves an FirmwareClass instance which contains all the data info of the info.
|
|
|
|
### 3.1.1 NodeTree Format
|
|
|
|
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?:
|
|
|
|
- A Root Node is initialized.
|
|
|
|
- Use the ?FV Signature? as FV key to split Whole FD Data. ?FV0?, ?FV1?, ?FV2?? Node created.
|
|
|
|
- After FV level Node created, use the ?Ffs Data Size? as FFS key to split each FV Data. ?Ffs0?...Node created.
|
|
|
|
- After FFS level Node created, use the ?Section Data Size? as Section key to split each Ffs Data. ?Section0?...Node created.
|
|
|
|
- If some of Section includes other Sections, continue use the ?Section Data Size? as Section key to split each Section Data.
|
|
|
|
- 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)
|
|
|
|
|
|
|
|
? Figure 2. The NodeTree format
|
|
|
|
### 3.1.2 Node Factory and Product
|
|
|
|
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.
|
|
|
|
Each Node have its Factory to create Product and use Product ParserData function to deal with the data.
|
|
|
|
## 3.2 GuidTool
|
|
|
|
There are two ways to set the GuidTool. One from Config file, another from environment variables.
|
|
|
|
Current GuidTool first check if has Config file.
|
|
|
|
- If have, load the config GuidTool Information.
|
|
|
|
- Else get from environment variables.
|
|
|
|
### 3.2.1 Get from Config file
|
|
|
|
- Config file should in same folder with FMMT.py or the path in environment variables.
|
|
|
|
- Content should follow the format:
|
|
|
|
***ToolsGuid ShortName Command***
|
|
|
|
### 3.2.2 Get from Environment Variables
|
|
|
|
- The GuidTool Command used must be set in environment variables.
|
|
|
|
### 3.2.3 Edk2 Based GuidTool
|
|
|
|
| ***Guid*** | ***ShortName*** | ***Command*** |
|
|
| ------------------------------------------ | --------------- | --------------------- |
|
|
| ***a31280ad-481e-41b6-95e8-127f4c984779*** | ***TIANO*** | ***TianoCompress*** |
|
|
| ***ee4e5898-3914-4259-9d6e-dc7bd79403cf*** | ***LZMA*** | ***LzmaCompress*** |
|
|
| ***fc1bcdb0-7d31-49aa-936a-a4600d9dd083*** | ***CRC32*** | ***GenCrc32*** |
|
|
| ***d42ae6bd-1352-4bfb-909a-ca72a6eae889*** | ***LZMAF86*** | ***LzmaF86Compress*** |
|
|
| ***3d532050-5cda-4fd0-879e-0f7f630d5afb*** | ***BROTLI*** | ***BrotliCompress*** |
|