NAND Flash Components
OFRAK includes a flash component that can unpack and pack a raw flash dump that includes out-of-band (OOB) data. A raw dump includes this extra data that make it hard to analyze without separating the "useful" data from the OOB data.
This page covers what a typical flash dump may look like and how to get started with using the flash components.
A Typical Flash Dump
A typical flash dump looks something like this:
This pattern may continue for the entire flash chip or could have fields in the header or tail block that show the size of the region that includes OOB data.
Other examples are more complex. Sometimes this is due to the fact that not all of the dump is ECC protected or needs OOB data. In such cases, delimiters or magic bytes are necessary to show the area. An example format:
Last Data Block
This format is interesting because it has a different sized tail block as well as different delimiters to represent the type of block. The FlashUnpacker is able to handle these different types of fields by providing attributes in FlashAttributes that also includes a FlashEccAttributes. We will describe the other parts of these attributes and how to use them later in this page.
Types of Fields
The class FlashFieldType contains field types that are commonly encountered in flash dumps:
DATA = 0
ECC = 1
ALIGNMENT = 2
MAGIC = 3
DATA_SIZE = 4
ECC_SIZE = 5
CHECKSUM = 6
DELIMITER = 7
TOTAL_SIZE = 8
DATAis the "useful" information in the dump.
ECCare the most common OOB data with several common algorithms for verifying and correcting the data.
ALIGNMENTcan be used for padding to fill an entire block or page.
MAGICis in some dumps that are not entirely covered in OOB data. These bytes indicate the start of the OOB inclusive region.
DATA_SIZEindicates the expected size of the
ECC_SIZEindicates the size of the
CHECKSUMensures that the data is read as expected.
DELIMITERmay be placed between fields in a block or to indicate what type of block it is.
TOTAL_SIZEindicates the size of the entire region that includes OOB data.
This class can be overridden or augmented if other field types are encountered.
A FlashAttributes must be provided in order to use the flash component. As with other aspects of OFRAK, this can be modified and overridden if it does not work specifically for your use case.
The FlashAttributes is necessary for communicating the information necessary to understand your specific flash format.
The only required field is the
data_block_format. These block formats are specified using an ordered
Iterable[FlashField] to describe the block.
This dataclass uses the previously shown
Enum with our various field types. We just need to specify the field type and the size for each
FlashField and provide them in order. An example:
ecc_attributes are also important for any dumps that include ECC. You have the option of providing the algorithms for encoding, decoding, and correcting the data. In addition, this is where the magic and any delimiter bytes are specified. See FlashEccAttributes for more information.
Running the Flash components
The Flash components can be used like any other OFRAK components. The first step is to tag a resource as a FlashResource and tag it with its flash resource attributes:
# Create root resource and tag
root_resource = await ofrak_context.create_root_resource_from_file(IN_FILE)
# Add our attributes
See Example 9: Flash Modification for example usage of these components.