OpenixCard

https://github.com/yuzukitsuru/openixcard
Admin
OpenixCard is an open-source tool for dumping, unpacking, and flashing Allwinner Linux IMG files on...
Tokens:11,400
Snippets:108
Trust Score:9.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install OpenixCard on Arch Linux

Source: https://github.com/yuzukitsuru/openixcard/blob/master/README.md

Installs OpenixCard using the AUR helper 'yay'. Ensure you have 'yay' or another AUR helper installed.

```bash
yay -S openixcard
```

--------------------------------

### Build OpenixCard from Source

Source: https://github.com/yuzukitsuru/openixcard/blob/master/README.md

Clones the OpenixCard repository, installs build dependencies, and compiles the project using CMake and Make.

```bash
# Download the source code
git clone --recursive --depth 1 https://github.com/YuzukiTsuru/OpenixCard

# Download the depends
sudo apt install cmake build-essential automake autoconf libconfuse-dev pkg-config

# Make build directory
mkdir build
cd build

# Make
cmake .. && make -j
```

--------------------------------

### OpenixCard Exception Handling Example

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Demonstrates how to catch various OpenixCard-specific exceptions derived from std::runtime_error. Ensure necessary headers are included.

```cpp
#include "exception.h"
#include <iostream>

void example_error_handling(const std::string &img_path, const std::string &dir_path) {
    try {
        // Throws file_open_error if the file doesn't exist
        // (OpenixCard::check_file calls std::filesystem::exists)
        if (!std::filesystem::exists(img_path)) {
            throw file_open_error(img_path);
            // what() => "Fail to open file: /path/to/file.img."
        }

        // Thrown by unpack_target_image() on return code 5
        // what() => "File: firmware.img is not Allwinner image."
        throw file_format_error(img_path);

        // Thrown when no -u/-d/-p/-s flag is provided
        // what() => "Operate ERROR, You must specify a Operator."
        throw operator_missing_error();

        // Thrown on argparse runtime_error (unknown flag, etc.)
        // what() => "Operate ERROR: unrecognized arguments: --foo."
        throw operator_error("unrecognized arguments: --foo");

        // Thrown when no positional input argument is given
        // what() => "No file Provide."
        throw no_file_provide_error();

    } catch (const file_open_error &e) {
        std::cerr << "[FILE ERROR] " << e.what() << std::endl;
    } catch (const file_format_error &e) {
        std::cerr << "[FORMAT ERROR] " << e.what() << std::endl;
    } catch (const operator_missing_error &e) {
        std::cerr << "[USAGE ERROR] " << e.what() << std::endl;
    } catch (const std::runtime_error &e) {
        std::cerr << "[ERROR] " << e.what() << std::endl;
    }
}
```

--------------------------------

### OpenixCard Usage Examples

Source: https://github.com/yuzukitsuru/openixcard/blob/master/README.md

Demonstrates various command-line options for OpenixCard, including unpacking, dumping, packing, and size checking of Allwinner IMG files.

```bash
OpenixCard -u  <img>   - Unpack Allwinner image to target
OpenixCard -uc <img>   - Unpack Allwinner image to target and generate Allwinner image partition table cfg
OpenixCard -d  <img>   - Convert Allwinner image to regular image
OpenixCard -p  <dir>   - pack dumped Allwinner image to regular image from folder
OpenixCard -s  <img>   - Get the accurate size of Allwinner image
```

--------------------------------

### Define a Flash Image with Partitions

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Example of defining a flash image with specific partitions. This configuration is used to create a nand-pcm038.img with 'barebox' and 'root' partitions.

```config
image nand-pcm038.img {
	  flash {
	  }
	  flashtype = "nand-64M-512"
	  partition barebox {
		  image = "barebox-pcm038.bin"
		  size = 512K
	  }
	  partition root {
		  image = "root-nand.jffs2"
		  size = 24M
	  }
  }
```

--------------------------------

### Configure HDImage with GPT

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Configure an hdimage with a GUID Partition Table (GPT) and specify its location. Partitions must begin after the GPT table.

```plaintext
image foo {
	hdimage {
		gpt = true
		gpt-location = 64K
	}

	partition bootloader {
		in-partition-table = false
		offset = 0
		image = "/path/to/bootloader.img"
	}

	partition rootfs {
		offset = 1M
		image = "rootfs.ext4"
	}
}
```

--------------------------------

### CLI: Get Accurate Image Size

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Calculates the minimum SD card size required to flash a firmware image by unpacking it and summing partition sizes with Allwinner-specific offsets.

```bash
# Get the accurate size required for the target storage device
OpenixCard -s sunxi-board.img

# Expected output:
# [INFO] Getting accurate size of Allwinner img...
# [INFO]   Partition: 'boot-resource'    768.00  MB - 1536    KB
# [INFO]   Partition: 'boot'             32.00   MB - 32768   KB
# [INFO]   Partition: 'env'              16.00   MB - 16384   KB
# [INFO]   Partition: 'rootfs'           512.00  MB - 524288  KB
# [DATA] The accurate size of image: 1328MB, 1360025KB
```

--------------------------------

### Get Accurate Image Size (CLI)

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Calculates and reports the minimum SD card size required to flash a firmware image by unpacking it, reading partition information, and summing sizes with compensation offsets.

```APIDOC
## CLI: Get Accurate Image Size

Unpacks the image, reads the `sys_partition.fex` partition table, sums all partition sizes, and adds Allwinner-specific compensating offsets (GPT location: 1MB, boot0 offset: 8KB, boot-packages offset: ~16MB). Reports the minimum SD card size needed to flash the firmware.

```bash
# Get the accurate size required for the target storage device
OpenixCard -s sunxi-board.img

# Expected output:
# [INFO] Getting accurate size of Allwinner img...
# [INFO]   Partition: 'boot-resource'    768.00  MB - 1536    KB
# [INFO]   Partition: 'boot'             32.00   MB - 32768   KB
# [INFO]   Partition: 'env'              16.00   MB - 16384   KB
# [INFO]   Partition: 'rootfs'           512.00  MB - 524288  KB
# [DATA] The accurate size of image: 1328MB, 1360025KB
```
```

--------------------------------

### Define a JFFS2 Filesystem Image

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Example of defining a jffs2 filesystem image. This configuration specifies the name, size, and mountpoint for the 'root' filesystem.

```config
image root-nand.jffs2 {
	  name = "root"
	  jffs2 {}
	  size = 24M
	  mountpoint = "/"
  }
```

--------------------------------

### Fix binutils Bug for Compilation

Source: https://github.com/yuzukitsuru/openixcard/blob/master/README.md

Installs a newer version of binutils to resolve compilation errors on Ubuntu 20.04 related to the 'ar' command.

```bash
sudo apt-get install texinfo

wget https://ftp.gnu.org/gnu/binutils/binutils-2.38.tar.xz && \
  tar xvf binutils-2.38.tar.xz && \
  cd binutils-2.38 && \
  ./configure --prefix=/usr/local && \
  make
  
sudo make install
```

--------------------------------

### C API: Initialize Decryption Contexts

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Initializes RC6 decryption contexts and the TwoFish key required for unpacking Allwinner firmware. Must be called once before any `unpack_image` operation.

```c
#include "OpenixIMG.h"

int main() {
    // Initialize all crypto contexts before unpacking
    crypto_init();

    // RC6 contexts are now ready:
    //   header_ctx      - key: { 0x00...0x00, 'i' }  (256-bit)
    //   fileheaders_ctx - key: { 0x01...0x01, 'm' }  (256-bit)
    //   filecontent_ctx - key: { 0x02...0x02, 'g' }  (256-bit)
    // TwoFish key: Fibonacci-seeded 128-byte array starting with [5, 4, 9, ...]

    int result = unpack_image("sunxi-board.img", "output_dir", 0);
    if (result != 0) {
        fprintf(stderr, "unpack_image failed with code %d\n", result);
        // Error codes:
        // 2 = cannot open input file
        // 3 = invalid file size (<= 0)
        // 4 = memory allocation failure
        // 5 = not an Allwinner IMAGEWTY image (bad magic / unsupported version)
    }
    return result;
}
```

--------------------------------

### crypto_init - Initialize Decryption Contexts (C API)

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Initializes the necessary RC6 decryption contexts for image header, file headers, and file content, along with the TwoFish key for non-FEX content. This function must be called once before any `unpack_image` operation.

```APIDOC
## C API: `crypto_init` — Initialize Decryption Contexts

Initializes the three RC6 decryption contexts (for image header, file headers, and file content) and the TwoFish key used for non-FEX file content. Must be called once before any `unpack_image` call. Uses fixed, known-constant keys embedded in the Allwinner firmware format specification.

```c
#include "OpenixIMG.h"

int main() {
    // Initialize all crypto contexts before unpacking
    crypto_init();

    // RC6 contexts are now ready:
    //   header_ctx      - key: { 0x00...0x00, 'i' }  (256-bit)
    //   fileheaders_ctx - key: { 0x01...0x01, 'm' }  (256-bit)
    //   filecontent_ctx - key: { 0x02...0x02, 'g' }  (256-bit)
    // TwoFish key: Fibonacci-seeded 128-byte array starting with [5, 4, 9, ...]

    int result = unpack_image("sunxi-board.img", "output_dir", 0);
    if (result != 0) {
        fprintf(stderr, "unpack_image failed with code %d\n", result);
        // Error codes:
        // 2 = cannot open input file
        // 3 = invalid file size (<= 0)
        // 4 = memory allocation failure
        // 5 = not an Allwinner IMAGEWTY image (bad magic / unsupported version)
    }
    return result;
}
```
```

--------------------------------

### Generate Disk Image with GenIMG Wrapper

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Use the GenIMG class to wrap the genimage tool for assembling disk images. It takes paths for the configuration file, partition image files, and the output directory. The status of the generation can be checked, and the process can be re-run with different parameters.

```cpp
#include "GenIMG.h"
#include <iostream>

int main() {
    // GenIMG(config_path, image_input_path, output_path)
    //   config_path  - path to .cfg file describing partition layout
    //   image_path   - directory containing partition image files (*.fex)
    //   output_path  - destination directory for the generated image
    GenIMG gen(
        "/tmp/sunxi-board.img.dump/sunxi-board.cfg",  // partition layout cfg
        "/tmp/sunxi-board.img.dump",                  // input files directory
        "/tmp/sunxi-board.img.dump.out"               // output directory
    );

    // Check if generation succeeded
    int status = gen.get_status();
    if (status == 0) {
        std::cout << "Image generated successfully" << std::endl;
        // Output image is at: /tmp/sunxi-board.img.dump.out/sunxi-board.img
    } else if (status == -EINVAL) {
        std::cerr << "Invalid cfg file" << std::endl;
    } else {
        std::cerr << "genimage failed with status: " << status << std::endl;
    }

    // Re-run with different parameters (reuses existing temp dirs)
    gen.re_run_genimage(
        "/tmp/other-board.cfg",
        "/tmp/other-board.dump",
        "/tmp/other-board.out"
    );

    return 0;
}
```

--------------------------------

### CLI: Pack Dumped Directory to Image

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Re-assembles a directory containing firmware components back into a flashable Allwinner-compatible disk image. Requires a .cfg file generated by -uc mode or manually crafted.

```bash
# After modifying files in the unpacked directory:
ls sunxi-board.img.dump/
# boot0_sdcard.fex  boot_package.fex  boot.fex  env.fex
# rootfs.fex  sunxi-board.cfg  image.cfg  blank.fex

# Re-pack the directory into a flashable image
OpenixCard -p sunxi-board.img.dump/

# Expected output:
# [INFO] Generating target image...
# [INFO] Generate Done! Your image file is at sunxi-board.img.dump/ Cleaning up...

# The output image is placed inside the input directory:
ls sunxi-board.img.dump/sunxi-board.img
```

--------------------------------

### Parse Partition Table and Generate genimage CFG with FEX2CFG

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Use FEX2CFG to parse Allwinner sys_partition.fex files and generate genimage-compatible .cfg files. The constructor reads and parses the partition data, and save_file writes the generated configuration. It can also query image name and total size, and regenerate the cfg with partition table type overrides.

```cpp
#include "FEX2CFG.h"
#include <iostream>

int main() {
    // Construct with the path to the unpacked image dump directory
    // Constructor reads sys_partition.fex, classifies, parses, and generates cfg
    FEX2CFG fex2cfg("/tmp/sunxi-board.img.dump");

    // Save the generated genimage cfg to the dump directory
    // Returns the full path to the saved .cfg file
    std::string cfg_path = fex2cfg.save_file("/tmp/sunxi-board.img.dump");
    std::cout << "CFG saved to: " << cfg_path << std::endl;
    // Output: CFG saved to: /tmp/sunxi-board.img.dump/sunxi-board.cfg

    // Query image name (derived from directory name, stripped of extension)
    std::string name = fex2cfg.get_image_name();
    std::cout << "Image name: " << name << std::endl;
    // Output: Image name: sunxi-board

    // Get total required image size in KB (sum of all partitions + compensations)
    // Compensations: GPT(1MB) + boot0(8KB) + boot-packages(~16MB)
    uint size_kb = fex2cfg.get_image_real_size(/*print=*/true);
    std::cout << "Total size: " << size_kb / 1024 << " MB" << std::endl;
    // Output:
    //   Partition: 'boot-resource'  768.00MB - 1536  KB
    //   Partition: 'boot'            32.00MB - 32768 KB
    //   Partition: 'rootfs'         512.00MB - 524288 KB
    //   Total size: 1328 MB

    // Regenerate cfg with a specific partition table type override
    fex2cfg.regenerate_cfg_file(partition_table_type::gpt);
    fex2cfg.save_file("/tmp/sunxi-board.img.dump");

    return 0;
}
```

--------------------------------

### Configure Project and Include Directories

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Sets the minimum CMake version, project name, and includes necessary directories for the project's source files and libraries.

```cmake
cmake_minimum_required(VERSION 3.5)

project(OpenixIMG)

include_directories(
        include
        lib/twofish/src
        lib/rc6/src
)
```

--------------------------------

### Define OpenixIMG Library and Link Dependencies

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Creates the OpenixIMG static library from specified source files and links it with external libraries and include directories.

```cmake
add_library(OpenixIMG src/OpenixIMG.c ../GenIMG/GenimageWrapper.c)
target_include_directories(OpenixIMG PRIVATE ${CONFUSE_INCLUDE_DIRS})
target_link_libraries(OpenixIMG twofish rc6 ${CONFUSE_LIBRARIES})
target_compile_options(OpenixIMG PRIVATE ${CONFUSE_CFLAGS_OTHER})
```

--------------------------------

### Configure RC6 Library Build

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/lib/rc6/CMakeLists.txt

Sets the minimum CMake version, names the project, specifies include directories, and adds the RC6 source file to create a static library.

```cmake
cmake_minimum_required(VERSION 3.5)

project(rc6)

include_directories(src)

add_library(rc6 src/rc6.c)
```

--------------------------------

### Pack a Dumped Directory Back to Image (CLI)

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Re-assembles a previously unpacked directory (potentially modified) back into a flashable Allwinner-compatible disk image using the embedded `genimage` tool. Requires a `.cfg` file in the directory.

```APIDOC
## CLI: Pack a Dumped Directory Back to Image

Re-assembles a previously unpacked (and optionally modified) directory back into a flashable Allwinner-compatible disk image. The directory must contain a `.cfg` file (not named `image.cfg`) generated by the `-uc` mode or manually crafted. Uses the embedded `genimage` tool internally.

```bash
# After modifying files in the unpacked directory:
ls sunxi-board.img.dump/
# boot0_sdcard.fex  boot_package.fex  boot.fex  env.fex
# rootfs.fex  sunxi-board.cfg  image.cfg  blank.fex

# Re-pack the directory into a flashable image
OpenixCard -p sunxi-board.img.dump/

# Expected output:
# [INFO] Generating target image...
# [INFO] Generate Done! Your image file is at sunxi-board.img.dump/ Cleaning up...

# The output image is placed inside the input directory:
ls sunxi-board.img.dump/sunxi-board.img
```
```

--------------------------------

### Unpack Allwinner Image to Folder

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Extracts all embedded files from an Allwinner IMAGEWTY .img file into a directory. The tool decrypts the image and writes each embedded file to disk alongside an image.cfg manifest. The output directory is named <input>.dump.

```bash
# Unpack firmware image - output goes to ./sunxi-board.img.dump/
OpenixCard -u sunxi-board.img

# Expected output:
#  _____             _     _____           _
# |     |___ ___ ___|_|_ _|     |___ ___ _| |
# |  |  | . | -_|   | |_'_|   --| .'|  _| . |
# |_____|  _|___|_|_|_|_,_|_____|__,|_| |___|
#       |_|
# [OpenixIMG INFO] Decrypting IMG header...
# [OpenixIMG INFO] IMG version is: 0x300
# [OpenixIMG INFO] Decrypting IMG file contents...
# [OpenixIMG INFO] Writing the IMG config data...
# [INFO] Unpack Done! Your image file is at sunxi-board.img.dump

# Contents of sunxi-board.img.dump/: 
#   image.cfg         <- manifest listing all embedded files
#   boot0_sdcard.fex
#   boot_package.fex
#   sys_partition.fex <- Allwinner partition table (INI-like format)
#   env.fex
#   boot.fex
#   rootfs.fex
#   ...
```

--------------------------------

### Dump Allwinner Image to Standard Raw Disk Image

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Converts an Allwinner .img directly into a standard raw disk image. This is a combined operation that unpacks, parses, generates CFG, runs genimage, and cleans up temporary files. The output is a single .img.dump.out file.

```bash
# Convert Allwinner image to a regular flashable image
OpenixCard -d sunxi-board.img

# Expected output:
# [INFO] Converting input file: sunxi-board.img
# [INFO] Convert Done! Parsing the partition tables...
# [INFO]   Partition: 'boot-resource'    768.00 MB - ...
# [INFO] Parse Done! Generating target image...
# [INFO] Generate Done! Your image file is at sunxi-board.img.dump.out
# [INFO] Cleaning up...

# Flash the resulting standard image to an SD card:
sudo dd if=sunxi-board.img.dump.out of=/dev/sdX bs=4M status=progress
```

--------------------------------

### Define OpenixCard Library Sources

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixCard/CMakeLists.txt

Uses GLOB to find all .cpp files in the current directory and in the payloads subdirectory for the OpenixCard library.

```cmake
file(GLOB libOpenixCardSource *.cpp)
file(GLOB libOpenixCardPayloads payloads/*.cpp)
```

--------------------------------

### Find and Check PkgConfig Modules

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Uses PkgConfig to find and check for the 'libconfuse' library, which is required for the GenimageWrapper.c component.

```cmake
# Find libconfuse for GenimageWrapper.c
find_package(PkgConfig REQUIRED)
pkg_check_modules(CONFUSE REQUIRED libconfuse)
```

--------------------------------

### Configure Twofish Library Build

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/lib/twofish/CMakeLists.txt

Sets the minimum CMake version and project name. Includes the source directory and adds the Twofish library source file.

```cmake
cmake_minimum_required(VERSION 3.5)

project(twofish)

include_directories(src)

add_library(twofish src/twofish.c)
```

--------------------------------

### Unpack Image and Generate Partition Table CFG

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

Unpacks the image and additionally converts the sys_partition.fex partition table into a genimage-compatible .cfg file. This CFG file is required for the --pack operation and describes partition layout with correct offsets.

```bash
# Unpack and generate partition cfg
OpenixCard -uc sunxi-board.img

# Expected output (after unpack completion):
# [INFO] Unpack Done! Your image file is at sunxi-board.img.dump
# [INFO]   Partition: 'boot-resource'    768.00 MB - 1536   KB
# [INFO]   Partition: 'boot'             32.00  MB - 32768  KB
# [INFO]   Partition: 'env'              16.00  MB - 16384  KB
# [INFO]   Partition: 'rootfs'           512.00 MB - 524288 KB
# [INFO]   Partition: 'UDISK'           Remaining space.
# [INFO] Parse Done! Your cfg file is at sunxi-board.img.dump/sunxi-board.cfg

# Generated sunxi-board.cfg looks like:
# image sunxi-board.img {
#     hdimage{
#         partition-table-type = "hybrid"
#         gpt-location = 1M
#     }
#     partition boot0 {
#         in-partition-table = "no"
#         image = "boot0_sdcard.fex"
#         offset = 8K
#     }
#     partition boot-packages {
#         in-partition-table = "no"
#         image = "boot_package.fex"
#         offset = 16400K
#     }
#     partition boot-resource {
#         partition-type = 0xC
#         image = "boot-resource.fex"
#         size = 1536K
#     }
#     partition rootfs {
#         image = "rootfs.fex"
#         size = 524288K
#     }
# }
```

--------------------------------

### Link OpenixCard Library Dependencies

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixCard/CMakeLists.txt

Links the libOpenixCard library with its private dependencies: OpenixIMG, inicpp, and GenIMG.

```cmake
target_link_libraries(libOpenixCard PRIVATE OpenixIMG inicpp GenIMG)
```

--------------------------------

### Define Executable and Link Libraries in CMake

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/CMakeLists.txt

Defines the main executable for the project and links it with necessary libraries and directories. Ensure all required dependencies are found and specified here.

```cmake
add_executable(OpenixCard main.cpp)
target_link_libraries(OpenixCard PRIVATE libOpenixCard OpenixIMG inicpp GenIMG ${CONFUSE_LIBRARIES})
target_link_directories(OpenixCard PRIVATE ${CONFUSE_LIBRARY_DIRS})
```

--------------------------------

### Find and Configure libconfuse Dependency

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Uses PkgConfig to find the libconfuse library, ensuring that its include directories and libraries are correctly set up for the GenIMG build. This is crucial for projects depending on libconfuse.

```cmake
# Find libconfuse
find_package(PkgConfig REQUIRED)
pkg_check_modules(CONFUSE REQUIRED libconfuse)
```

--------------------------------

### Execute Autotools Build for genimage-src

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Configures and builds the genimage-src component using autotools. This involves running aclocal, autoconf, automake, configure, and make within the target build directory. These commands are executed as custom commands before the GenIMG target is linked.

```cmake
# autotools build
add_custom_command(
        TARGET GenIMG
        PRE_LINK
        WORKING_DIRECTORY ${LIBGENIMAGE_TARGET_BUILD_DIR}
        COMMAND aclocal
)

add_custom_command(
        TARGET GenIMG
        PRE_LINK
        WORKING_DIRECTORY ${LIBGENIMAGE_TARGET_BUILD_DIR}
        COMMAND autoconf -i && automake --add-missing
)

add_custom_command(
        TARGET GenIMG
        PRE_LINK
        WORKING_DIRECTORY ${LIBGENIMAGE_TARGET_BUILD_DIR}
        COMMAND chmod a+x configure && ./configure && make
)
```

--------------------------------

### Add OpenixCard Library Target

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixCard/CMakeLists.txt

Adds the OpenixCard library target using the discovered source files.

```cmake
add_library(libOpenixCard ${libOpenixCardSource} ${libOpenixCardPayloads})
```

--------------------------------

### Discover GenIMG Source Files

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Uses CMake's GLOB command to find all .c files in the current directory for the GenIMG library. This simplifies source file management.

```cmake
file(GLOB GenIMGSource *.c)
```

--------------------------------

### Create Build Directory for genimage-src

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Ensures that the target build directory for the genimage-src component exists before proceeding with the build. This is a prerequisite for copying files and running build commands.

```cmake
file(MAKE_DIRECTORY ${LIBGENIMAGE_TARGET_BUILD_DIR})
```

--------------------------------

### Configure Optional Test Executable Build

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Defines a build option to enable or disable the compilation of the OpenixIMG test executable.

```cmake
option(BUILD_T_OpenixIMG "Set to ON to build OpenixIMG Test" OFF)
```

--------------------------------

### unpack_image - Unpack an IMAGEWTY Image (C API)

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

The core C function for reading an IMAGEWTY `.img` file, decrypting its contents using RC6, extracting all embedded files to a specified directory, and generating an `image.cfg` manifest. It supports multiple header versions and automatically detects unencrypted images.

```APIDOC
## C API: `unpack_image` — Unpack an IMAGEWTY Image

Core C function that reads an IMAGEWTY `.img` file, decrypts its header and all file entries using RC6, extracts every embedded file to the output directory, and writes an `image.cfg` manifest. Supports both header version `0x0100` and `0x0300`. Automatically detects unencrypted images (A31 and newer SoCs where the magic `IMAGEWTY` is present in plaintext).

```c
#include "OpenixIMG.h"
#include <stdio.h>

int main(void) {
    crypto_init();

    // unpack_image(input_file, output_directory, is_absolute_path)
    //   is_absolute = 0: output paths prefixed with "./"
    //   is_absolute = 1: output paths prefixed with "/"
    int ret = unpack_image(
        "/path/to/sunxi-t113.img",   // input IMAGEWTY firmware
        "/tmp/sunxi-t113-unpacked",  // output directory (created if absent)
        1                            // use absolute path prefix
    );

    switch (ret) {
        case 0:
            printf("Success. Files extracted to /tmp/sunxi-t113-unpacked/\n");
            // Files written include: image.cfg, boot0_sdcard.fex,
            // boot_package.fex, sys_partition.fex, env.fex, rootfs.fex, etc.
            break;
        case 2: fprintf(stderr, "Error: Cannot open image file\n");        break;
        case 3: fprintf(stderr, "Error: Image file has invalid size\n");   break;
        case 4: fprintf(stderr, "Error: Out of memory\n");                 break;
        case 5: fprintf(stderr, "Error: Not a valid IMAGEWTY image\n");    break;
    }
    return ret;
}
```
```

--------------------------------

### Build and Link Test Executable

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Conditionally builds the T_OpenixIMG executable if the BUILD_T_OpenixIMG option is enabled, linking it against the OpenixIMG library.

```cmake
if(BUILD_T_OpenixIMG)

add_executable(T_OpenixIMG test/T_OpenixIMG.c)
target_link_libraries(T_OpenixIMG OpenixIMG)

endif()
```

--------------------------------

### Include Configuration Fragment in Genimage

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Includes another configuration file fragment into the current genimage configuration. This is useful for reusing common settings, such as flash configurations, across multiple image definitions.

```cfg
include("foo.cfg")
```

--------------------------------

### Find and Check PkgConfig Modules in CMake

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/CMakeLists.txt

Finds and checks for required packages using PkgConfig. This is essential for managing external library dependencies and their build flags.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(CONFUSE REQUIRED libconfuse)
```

--------------------------------

### Copy genimage-src to Build Directory

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Uses a custom CMake command to copy the entire genimage-src directory to the target build directory. This ensures that the source files for genimage are available in the build environment for subsequent build steps, promoting cross-platform compatibility.

```cmake
# Copy genimage-src files to build directory using CMake for cross-platform compatibility
add_custom_command(
        TARGET GenIMG
        PRE_LINK
        COMMAND ${CMAKE_COMMAND} -E copy_directory "${LIBGENIMAGE_SOURCE_DIR}" "${LIBGENIMAGE_TARGET_BUILD_DIR}"
)
```

--------------------------------

### Define GenIMG Build Paths

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Sets CMake variables to define the source directory, target build directory, and the output library path for GenIMG. These variables ensure consistent paths across different build environments.

```cmake
set(LIBGENIMAGE_SOURCE_DIR "${CMAKE_SOURCE_DIR}/src/GenIMG/genimage-src")
set(LIBGENIMAGE_TARGET_BUILD_DIR "${CMAKE_BINARY_DIR}/thirdparty/genimage-src/")
set(LIBGENIMAGE_TARGET_LIBRARY "${CMAKE_BINARY_DIR}/thirdparty/genimage-src/libgenimage.a")
```

--------------------------------

### GNU General Public License

Source: https://github.com/yuzukitsuru/openixcard/blob/master/README.md

The license under which OpenixCard is distributed. This snippet shows the beginning of the license text.

```text
GNU GENERAL PUBLIC LICENSE Version 2, June 1991
                        
Copyright (c) 2022, YuzukiTsuru <GloomyGhost@GloomyGhost.com>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.

See README and LICENSE for more details.
```

--------------------------------

### Add GenIMG Library Target

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/CMakeLists.txt

Defines the GenIMG library target, including its source files and header files. It also links against the libgenimage.a static library, the PkgConfig found libconfuse, and the Threads library. Compile options from libconfuse are also applied.

```cmake
add_library(GenIMG ${GenIMGSource} GenIMG.cpp GenIMG.h GenimageWrapper.h)
target_include_directories(GenIMG PRIVATE ${CONFUSE_INCLUDE_DIRS})
target_link_libraries(GenIMG PRIVATE ${LIBGENIMAGE_TARGET_LIBRARY} Threads::Threads ${CONFUSE_LIBRARIES})
target_compile_options(GenIMG PRIVATE ${CONFUSE_CFLAGS_OTHER})
```

--------------------------------

### Add Subdirectories for Libraries

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/OpenixIMG/CMakeLists.txt

Includes subdirectories for external libraries, allowing their CMake build systems to be integrated into the main project.

```cmake
add_subdirectory(lib/twofish)
add_subdirectory(lib/rc6)
```

--------------------------------

### Configure Holes in Partition

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Configure 'holes' directly within a partition definition when the image is not explicitly declared. This simplifies configuration for basic use cases.

```plaintext
image bar {
	hdimage {}

	partition bootloader {
		in-partition-table = false
		offset = 0
		image = "/path/to/bootloader.img"
		holes = {"(440; 512)"}
	}

	partition rootfs {
		offset = 1M
		image = "rootfs.ext4"
	}
}
```

--------------------------------

### Include Subdirectories in CMake

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/CMakeLists.txt

Includes other CMake subdirectories for modular project structure. Use this to incorporate different components of the project into the build.

```cmake
add_subdirectory(GenIMG)
```

```cmake
add_subdirectory(OpenixIMG)
```

```cmake
add_subdirectory(OpenixCard)
```

--------------------------------

### Define File Image with Holes

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Explicitly define a file image and specify ranges that do not contain meaningful data. This allows for overlapping partitions or metadata.

```plaintext
image foo {
	hdimage {
		gpt = true
		gpt-location = 64K
	}

	partition bootloader {
		in-partition-table = false
		offset = 0
		image = "/path/to/bootloader.img"
	}

	partition rootfs {
		offset = 1M
		image = "rootfs.ext4"
	}
}

image /path/to/bootloader.img {
	file {
		holes = {"(440; 1K)", "(64K; 80K)"}
	}
}
```

--------------------------------

### C API: Unpack IMAGEWTY Image

Source: https://context7.com/yuzukitsuru/openixcard/llms.txt

The core C function to decrypt and extract files from an IMAGEWTY firmware image. Supports multiple header versions and automatically detects unencrypted images.

```c
#include "OpenixIMG.h"
#include <stdio.h>

int main(void) {
    crypto_init();

    // unpack_image(input_file, output_directory, is_absolute_path)
    //   is_absolute = 0: output paths prefixed with "./"
    //   is_absolute = 1: output paths prefixed with "/"
    int ret = unpack_image(
        "/path/to/sunxi-t113.img",   // input IMAGEWTY firmware
        "/tmp/sunxi-t113-unpacked",  // output directory (created if absent)
        1                            // use absolute path prefix
    );

    switch (ret) {
        case 0:
            printf("Success. Files extracted to /tmp/sunxi-t113-unpacked/\n");
            // Files written include: image.cfg, boot0_sdcard.fex,
            // boot_package.fex, sys_partition.fex, env.fex, rootfs.fex, etc.
            break;
        case 2: fprintf(stderr, "Error: Cannot open image file\n");        break;
        case 3: fprintf(stderr, "Error: Image file has invalid size\n");   break;
        case 4: fprintf(stderr, "Error: Out of memory\n");                 break;
        case 5: fprintf(stderr, "Error: Not a valid IMAGEWTY image\n");    break;
    }
    return ret;
}
```

--------------------------------

### Define Flash Section in Genimage

Source: https://github.com/yuzukitsuru/openixcard/blob/master/src/GenIMG/genimage-src/README.rst

Defines a flash chip configuration within a genimage file. Use this to specify parameters like erase block size and number of erase blocks for a particular flash device.

```cfg
flash nand-64M-512 {
		  pebsize = 16384
	  lebsize = 15360
	  numpebs = 4096
	  minimum-io-unit-size = 512
	  vid-header-offset = 512
	  sub-page-size = 512
  }
  ...
  image jffs2 {
	  flashtype = "nand-64M-512"
  }
```
Tokens:
Raw