Pkg.UBI — API for parsing UBI images and UBIFS file systems

Overview

The Pkg.UBI module contains the API for parsing UBI (Unsorted Block Image) containers and UBIFS (UBI File System) images.

UBI is a volume management layer for raw NAND flash, widely used in embedded Linux devices, routers, IoT hardware, and firmware images. A UBI image contains one or more logical volumes, each of which may hold a UBIFS file system, a kernel image, or other data.

UBIFS is a log-structured file system designed specifically for UBI volumes. It uses a B-tree index and supports transparent compression (LZO, zlib, ZSTD).

Enumerating UBI Volumes

The following code example demonstrates how to list volumes in a UBI image and reconstruct volume data:

from Pro.Core import *
from Pkg.UBI import *

def listVolumes(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = UBIObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    for i in range(obj.GetVolumeCount()):
        vol = obj.GetVolume(i)
        print("Volume %d: %s" % (i, vol.name))
    # reconstruct volume 0 data
    data = obj.GetVolumeData(0)

Enumerating UBIFS Files

The following code example demonstrates how to enumerate files in a UBIFS file system:

from Pro.Core import *
from Pkg.UBI import *

def enumerateFiles(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = UBIFSObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    nre = CFSNonRecursiveEnum(obj)
    nre.AddPath(obj.FSRootDirectory())
    while True:
        f = nre.Next(None)
        if not f:
            break
        entry = obj.FSGetEntry(f, None)
        if not entry.IsNull():
            print(entry.Name(), entry.DataSize())

Module API

Pkg.UBI module API.

Classes:

UBIFSObject()	This class represents a UBIFS (UBI File System).
UBIObject()	This class represents a UBI (Unsorted Block Image) container.

class UBIFSObject

Bases: Pro.Core.CFFObject

This class represents a UBIFS (UBI File System).

The class provides file system support through the CFS interface inherited from CFFObject. It parses the UBIFS B-tree index to provide directory listing and file reading with transparent decompression (LZO, zlib, ZSTD).

Methods:

GetMasterNode()	Returns the parsed UBIFS master node.
GetSuperblock()	Returns the parsed UBIFS superblock.

GetMasterNode() → Optional[object]

Returns the parsed UBIFS master node.

The master node contains the root index location and filesystem statistics such as total free, dirty, and used space.

Returns

Returns the master node object, or None if not available.

Return type

Optional[object]

GetSuperblock() → Optional[object]

Returns the parsed UBIFS superblock.

The superblock contains filesystem parameters such as LEB size, LEB count, default compression type, and format version.

Returns

Returns the superblock object, or None if not available.

Return type

Optional[object]

class UBIObject

Bases: Pro.Core.CFFObject

This class represents a UBI (Unsorted Block Image) container.

A UBI image contains one or more logical volumes, each composed of scattered logical eraseblocks (LEBs) that are reassembled by the parser. Volumes may contain raw data (kernel images, SquashFS) or a UBIFS file system.

Methods:

DumpVolume(index, out)	Writes volume metadata (name, type, size, etc.) to a text stream.
GetPebSize()	Returns the physical eraseblock (PEB) size in bytes.
GetVolume(index)	Returns the volume object at the given index.
GetVolumeCount()	Returns the number of volumes in the UBI image.
GetVolumeData(index, *[, wo])	Reconstructs the contiguous data of a volume into an NTContainer.

DumpVolume(index: int, out: Pro.Core.proTextStream) → None

Writes volume metadata (name, type, size, etc.) to a text stream.

Parameters

• index (int) – The zero-based volume index.

• out (proTextStream) – The output text stream.

GetPebSize() → int

Returns the physical eraseblock (PEB) size in bytes.

Returns

Returns the PEB size.

Return type

int

GetVolume(index: int) → Optional[object]

Returns the volume object at the given index.

Parameters

index (int) – The zero-based volume index.

Returns

Returns the volume object, or None if the index is invalid.

Return type

Optional[object]

GetVolumeCount() → int

Returns the number of volumes in the UBI image.

Returns

Returns the volume count.

Return type

int

GetVolumeData(index: int, *, wo: Optional[object] = None) → Pro.Core.NTContainer

Reconstructs the contiguous data of a volume into an NTContainer.

The volume’s scattered LEBs are read in order and written sequentially. Missing LEBs are filled with 0xFF bytes (erased NAND state).

Parameters

• index (int) – The zero-based volume index.

• wo (Optional[object]) – Optional wait object for aborting long operations.

Returns

Returns the volume data as an NTContainer. Returns an empty NTContainer if the index is invalid or the operation was aborted.

Return type

NTContainer