How Ventoy's VtoyTool Handles Loading and Booting of Virtual Disk Image Chains

Ventoy's VtoyTool bridges the gap between fragmented ISO files on USB storage and contiguous virtual disk access by translating sector mappings through a device-mapper interface and dispatching boot commands to the appropriate loader.

The VtoyTool component in the ventoy/Ventoy repository is a user-space utility that enables the boot loader to treat split or fragmented ISO images as single, contiguous virtual disks. By parsing runtime metadata generated by the Ventoy bootloader and translating virtual sectors to physical disk locations, VtoyTool allows seamless booting without modifying the original image files.

What Is VtoyTool and Its Role in Virtual Disk Chains

VtoyTool (the vtoytool binary) serves as the runtime command dispatcher and device-mapper helper for Ventoy's Linux environment. It interprets sub-commands such as vtoydm, loader, vtoydump, and vine_patch_loader to facilitate the transition from bootloader initialization to actual operating system execution.

The Binary Architecture and Command Dispatch

The entry point in VtoyTool/vtoytool.c maintains a static command table that routes execution to specialized handlers based on the first argument:

// VtoyTool/vtoytool.c (line 44-55)
static cmd_def g_cmd_list[] = {
    { "vine_patch_loader", vtoyvine_main },
    { "vtoydump",    vtoydump_main },
    { "loader",      vtoyloader_main },
    { "vtoydm",      vtoydm_main },
    ...
};

When invoked as vtoytool vtoydm, the binary executes vtoydm_main() from VtoyTool/vtoydm.c, which handles the critical sector mapping logic for virtual disk image chains. Similarly, the loader command triggers vtoyloader_main() to hand control over to the actual boot executable.

Mapping Fragmented ISO Images to Physical Sectors

Virtual disk image chains occur when a single ISO is split across non-contiguous regions of a USB drive. VtoyTool resolves these fragments using a sector-translation layer that maps logical ISO sectors to their physical locations on the storage device.

The Image Map File Structure

During initialization, the Ventoy bootloader writes an image-map file (typically ventoy_img.map) that records the correspondence between ISO sectors and disk sectors. Each entry follows the ventoy_img_chunk structure defined in VtoyTool/vtoytool.h:

// VtoyTool/vtoydm.c (line 52-60)
typedef struct ventoy_img_chunk {
    uint32_t img_start_sector;   // 2 KB sectors in the ISO
    uint32_t img_end_sector;     // inclusive
    uint64_t disk_start_sector;  // where the fragment lives on the USB
    uint64_t disk_end_sector;    // inclusive
} ventoy_img_chunk;

The function vtoydm_get_img_map_data() in VtoyTool/vtoydm.c (lines 79-87) reads this map into a global array g_img_chunk, storing the fragmentation metadata in memory for rapid sector translation during boot.

Sector Translation Logic in vtoydm.c

When the system requests a specific sector from the virtual ISO, vtoydm_map_iso_sector() performs the translation by iterating through the chunk array and calculating the offset:

// VtoyTool/vtoydm.c (line 86-99)
UINT64 vtoydm_map_iso_sector(UINT64 sector) {
    for (i = 0; i < g_img_chunk_num; i++) {
        if (sector >= g_img_chunk[i].img_start_sector &&
            sector <= g_img_chunk[i].img_end_sector) {
            return ((sector - g_img_chunk[i].img_start_sector) << 2) 
                   + g_img_chunk[i].disk_start_sector;
        }
    }
    return 0;
}

The bit-shift operation (<< 2) converts between the ISO's native 2 KB sector size and the standard 512-byte disk sectors used by the underlying block device.

Reading Virtual Disk Sectors Through the Device-Mapper Interface

VtoyTool exposes a file-like abstraction layer that allows ISO parsing libraries to read fragmented images as if they were contiguous files, hiding the complexity of the underlying physical layout.

The vtoydm_read_iso_sector Implementation

The core read operation opens the physical USB device once, seeks to the translated sector, and retrieves the data in 2 KB blocks:

// VtoyTool/vtoydm.c (line 102-130)
int vtoydm_read_iso_sector(UINT64 sector, void *buf) {
    disk_sector = vtoydm_map_iso_sector(sector);
    fd = open(g_disk_name, O_RDONLY | O_BINARY);
    lseek(fd, disk_sector * 512, SEEK_SET);
    read(fd, buf, 2048);
    close(fd);
}

This function ensures that any request for ISO sector N returns the correct data regardless of which physical disk fragment contains that sector.

Providing a File-Like API for ISO Parsers

Higher-level ISO readers (implemented in the biso_*.c modules) interact with the virtual disk through VtoyTool callbacks including vtoydm_open_file(), vtoydm_seek_file(), and vtoydm_read_file(). These functions internally utilize the sector translation layer, allowing standard ISO 9660 parsers to operate on fragmented images without modification.

Booting the Loader with the vtoytool loader Command

Once the virtual disk mappings are established, the loader command executes the final boot sequence, transitioning from the Ventoy environment to the target operating system's bootloader.

Execution Flow and Hook Scripts

The implementation in VtoyTool/vtoyloader.c reads the target executable path from /ventoy/loader_exec_file, appends optional command-line parameters from /ventoy/loader_exec_cmdline, and executes an optional hook script from /ventoy/loader_hook_cmd before invoking execv():

// VtoyTool/vtoyloader.c (line 62-68)
rc = vtoy_read_file_to_buf(EXEC_PATH_FILE, g_exec_file, sizeof(g_exec_file)-1);
// ...
cmdlist[0] = g_exec_file;
// ...
execv(cmdlist[0], cmdlist);

This modular approach allows Ventoy to support diverse boot configurations while maintaining a consistent interface for virtual disk image chains.

Practical Examples: Using vtoydm to Inspect Image Chains

You can manually inspect how VtoyTool translates sectors for a fragmented ISO using the vtoydm sub-command with the -p (print) flag:

# Print linear mapping table for a fragmented ISO

vtoytool vtoydm -p -f /ventoy/ventoy_img.map -d /dev/sda

Sample output showing two fragments mapped to different disk regions:

0 20971520 linear sda1 0
8388608 20971520 linear sda2 8388608

The output format conforms to the Linux kernel's dm-linear target expectations, expressing all offsets in 512-byte sectors. To trigger the actual boot sequence after mapping:

vtoytool loader

This reads the configured executable path, applies any defined hooks, and transfers control to the boot loader.

Summary

• VtoyTool acts as the runtime dispatcher and device-mapper helper in the Ventoy boot process, handling commands like vtoydm and loader from VtoyTool/vtoytool.c.
• Virtual disk image chains are managed through sector-translation logic in VtoyTool/vtoydm.c, which reads the ventoy_img.map file containing ventoy_img_chunk structures.
• Sector mapping converts 2 KB ISO sectors to 512-byte physical disk sectors using vtoydm_map_iso_sector(), enabling fragmented ISOs to appear as contiguous files.
• File-like API functions (vtoydm_read_iso_sector(), etc.) allow standard ISO parsers to operate on split images without awareness of the underlying fragmentation.
• Boot execution is handled by the loader command in VtoyTool/vtoyloader.c, which executes the target boot loader with optional command-line injections and hook scripts.

Frequently Asked Questions

How does VtoyTool handle ISO images that are split into multiple fragments on the USB drive?

VtoyTool reads a mapping file (ventoy_img.map) generated by the Ventoy bootloader that contains an array of ventoy_img_chunk structures. Each structure records the start and end sectors of an ISO fragment and its corresponding location on the physical disk. The function vtoydm_map_iso_sector() translates virtual ISO sector requests to physical disk sectors by looking up the appropriate chunk and calculating the offset.

What is the difference between the vtoydm and loader commands in VtoyTool?

The vtoydm command (implemented in VtoyTool/vtoydm.c) handles device-mapper operations, including reading the image map, translating sectors, and providing a linear mapping table for the kernel. The loader command (implemented in VtoyTool/vtoyloader.c) executes the actual boot sequence by reading the target executable path from /ventoy/loader_exec_file, applying command-line arguments and hooks, and calling execv() to start the boot loader.

Why does VtoyTool convert between 2 KB and 512-byte sectors?

ISO 9660 images traditionally use 2 KB (2048-byte) sectors, while Linux block devices and the device-mapper subsystem operate on 512-byte sectors. The translation occurs in vtoydm_map_iso_sector() using a left bit shift (<< 2), which multiplies the sector difference by 4 to convert from 2 KB units to 512-byte units before calculating the physical disk address.

Can VtoyTool boot an ISO image without the mapping file present?

No. The ventoy_img.map file is essential because it contains the ventoy_img_chunk data that tells VtoyTool where each fragment of the ISO resides on the USB drive. Without this mapping, vtoydm_get_img_map_data() would fail to populate the global chunk array, causing all sector translation requests in vtoydm_map_iso_sector() to return 0 and preventing successful boot.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}