How Ventoy Implements the Memdisk Boot Mode for Loading ISO Images from Memory

Ventoy's memdisk boot mode loads entire ISO images into system RAM, prepends a chain header structure, and delegates control to the GRUB memdisk module to boot the image as a virtual disk without writing to physical media.

Ventoy is an open-source multiboot USB solution that allows users to boot ISO images directly. Unlike standard loopback mounting, the memdisk boot mode enables direct execution from memory, eliminating USB read latency after boot. This article examines the source code in the ventoy/Ventoy repository to explain the complete implementation.

Architecture of the Memdisk Boot Mode

The implementation consists of three coordinated stages: configuration parsing, runtime detection during menu generation, and the actual memory loading sequence. These stages work together to seamlessly transition from file selection to RAM-based boot execution.

Step 1: Parsing the Auto-Memdisk Configuration

The process begins with a JSON configuration file that specifies which ISO images must boot from memory. Ventoy parses this auto_memdisk plugin in GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c.

The function ventoy_plugin_auto_memdisk_entry builds a linked list of paths from the JSON array:

static int ventoy_plugin_auto_memdisk_entry(VTOY_JSON *json, const char *isodisk)
{
    VTOY_JSON *pNode = NULL;
    auto_memdisk *node = NULL, *next = NULL;

    (void)isodisk;

    if (json->enDataType != JSON_TYPE_ARRAY) { return 0; }

    /* free any previous list */
    if (g_auto_memdisk_head) {
        for (node = g_auto_memdisk_head; node; node = next) {
            next = node->next;
            grub_free(node);
        }
        g_auto_memdisk_head = NULL;
    }

    /* build the new list */
    for (pNode = json->pstChild; pNode; pNode = pNode->pstNext) {
        if (pNode->enDataType == JSON_TYPE_STRING) {
            node = grub_zalloc(sizeof(auto_memdisk));
            if (node) {
                node->pathlen = grub_snprintf(node->isopath,
                                            sizeof(node->isopath),
                                            "%s", pNode->unData.pcStrVal);
                node->next = g_auto_memdisk_head;
                g_auto_memdisk_head = node;
            }
        }
    }
    return 0;
}

Each auto_memdisk node stores the full ISO path in isopath and its length in pathlen, maintaining the list in the global g_auto_memdisk_head variable.

Step 2: Runtime Detection and Menu Injection

During menu construction, Ventoy checks each discovered ISO against the auto-memdisk list. The function ventoy_plugin_check_memdisk in ventoy_plugin.c performs this comparison:

int ventoy_plugin_check_memdisk(const char *isopath)
{
    int len;
    auto_memdisk *node = NULL;

    if (!g_auto_memdisk_head) { return 0; }

    len = (int)grub_strlen(isopath);
    for (node = g_auto_memdisk_head; node; node = node->next) {
        if (node->pathlen == len &&
            ventoy_strncmp(node->isopath, isopath, len) == 0) {
            return 1;               /* match → memdisk mode */
        }
    }
    return 0;
}

When a match is found, the global flag g_ventoy_memdisk_mode (declared in GRUB2/MOD_SRC/grub-2.04/grub-core/normal/menu.c) is set to 1. This triggers the injection of a special menu entry in ventoy_cmd.c:

if (g_ventoy_memdisk_mode) {
    vtoy_dummy_menuentry(cmd, pos, len,
            "$VTLANG_MEMDISK_MODE",   /* “Boot in memdisk mode” */
            "second_memdisk");         /* special entry type */
}

This creates the "Boot in memdisk mode" option visible to users in the Ventoy boot menu.

Step 3: Loading the ISO into RAM

When the user selects the memdisk entry, the GRUB command vt_load_img_memdisk executes. Implemented in ventoy_cmd.c, this command handles memory allocation and image loading:

static grub_err_t ventoy_cmd_load_img_memdisk(grub_extcmd_context_t ctxt,
                                            int argc, char **args)
{
    int rc = 1;
    int headlen;
    char *buf = NULL;
    grub_file_t file;

    (void)ctxt;
    if (argc != 2) { return rc; }

    file = ventoy_grub_file_open(VENTOY_FILE_TYPE, "%s", args[0]);
    if (!file) { return 1; }

    headlen = sizeof(ventoy_chain_head);   /* small header used by Ventoy */

    /* Allocate a contiguous buffer (EFI vs BIOS differences handled) */
#ifdef GRUB_MACHINE_EFI
    buf = (char *)grub_efi_allocate_iso_buf(headlen + file->size);
#else
    buf = (char *)grub_malloc(headlen + file->size);
#endif

    /* Fill the header with OS parameters (kernel command line, etc.) */
    ventoy_fill_os_param(file, (ventoy_os_param *)buf);

    /* Read the whole ISO *after* the header */
    grub_file_read(file, buf + headlen, file->size);

    /* Export the buffer to GRUB as an environment variable */
    ventoy_memfile_env_set(args[1], buf, (ulonglong)file->size);

    grub_file_close(file);
    rc = 0;
    return rc;
}

The process executes four critical operations:

1. Buffer Allocation: Allocates a contiguous memory block sized for the ventoy_chain_head structure plus the full ISO size. EFI systems use grub_efi_allocate_iso_buf while BIOS systems use grub_malloc.
2. Header Preparation: The ventoy_fill_os_param function populates the header with OS-specific boot parameters.
3. Image Loading: The entire ISO is read into memory immediately after the header using grub_file_read.
4. Environment Export: The ventoy_memfile_env_set function registers the buffer with GRUB via the environment variable specified in args[1] (typically VTOY_MEM_DISK_STR).

Step 4: The GRUB Memdisk Module Handoff

Once the ISO resides in RAM and the environment variable VTOY_MEM_DISK_STR points to the buffer, control transfers to the GRUB memdisk module. This pre-compiled module, located at INSTALL/grub/*/memdisk.mod in the Ventoy installation, implements a block device driver that treats the memory buffer as a virtual disk.

The module reads the buffer address from the environment variable, creates a virtual block device interface, and presents the ISO image to the bootloader as if it were a physical disk. This allows the ISO's native bootloader—whether ISOLINUX, GRUB, or a UEFI stub—to execute normally, loading kernels and initramfs images directly from the memory-mapped ISO.

Configuration Example

To enable memdisk mode for specific ISOs, create a configuration file (managed via the Plugson UI at Plugson/www/plugson_auto_memdisk.html or manually edited) with the following structure:

{
    "auto_memdisk": [
        "/ISO/Win10_20H2.iso",
        "/ISO/Ubuntu-22.04.iso"
    ]
}

Place this file in the Ventoy partition. When Ventoy boots, it parses this list in ventoy_plugin.c and automatically presents the "Boot in memdisk mode" option for matching ISOs.

Summary

• Ventoy's memdisk boot mode enables booting ISO images directly from system RAM without extracting files to the USB drive.
• Configuration occurs via JSON in the auto_memdisk plugin, parsed by ventoy_plugin.c to build a path whitelist in g_auto_memdisk_head.
• Detection happens during menu generation through ventoy_plugin_check_memdisk(), which sets g_ventoy_memdisk_mode and injects a special menu entry via ventoy_cmd.c.
• Loading is handled by the vt_load_img_memdisk command, which allocates a contiguous buffer using grub_efi_allocate_iso_buf (UEFI) or grub_malloc (BIOS), prepends a ventoy_chain_head structure, reads the entire ISO into RAM, and exports the buffer via VTOY_MEM_DISK_STR.
• Execution transfers to the GRUB memdisk.mod module, which treats the RAM buffer as a virtual block device, allowing the ISO's native bootloader to execute.

Frequently Asked Questions

What is the difference between normal Ventoy boot and memdisk mode?

Normal Ventoy boot uses loopback mounting to access the ISO file directly from the USB drive, reading data on demand during the boot process. Memdisk mode, implemented in ventoy_cmd.c, loads the entire ISO image into RAM before booting begins, eliminating USB read latency after boot but requiring sufficient system memory to hold the complete image.

How much RAM is required to use memdisk mode?

The system must have enough free RAM to accommodate the full size of the ISO image plus the ventoy_chain_head header (typically less than 1 KB). For example, booting a 4 GB Windows ISO requires at least 4 GB of available memory above what the bootloader and kernel reserve. The allocation uses grub_efi_allocate_iso_buf on UEFI systems or grub_malloc on BIOS systems.

Can I use wildcards in the auto_memdisk JSON configuration?

Yes, the auto_memdisk plugin supports wildcard patterns when matching ISO paths. The ventoy_plugin_check_memdisk() function in ventoy_plugin.c compares each discovered ISO path against the configured list using length and string comparison operations, allowing path patterns to match multiple files without listing each individually.

Is memdisk mode compatible with both BIOS and UEFI systems?

Yes, the implementation handles both firmware types transparently. The vt_load_img_memdisk command uses conditional compilation (#ifdef GRUB_MACHINE_EFI) to select the appropriate memory allocator: grub_efi_allocate_iso_buf for UEFI environments and standard grub_malloc for BIOS systems. The GRUB memdisk.mod module works across both architectures once the buffer is allocated.

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