How webMAN MOD Implements NTFS and exFAT Support for External Storage Devices

webMAN MOD enables NTFS and exFAT support for external storage devices through a three-layer architecture comprising the FatFs filesystem driver, dynamic path detection with virtual mounting, and the prepNTFS content scanner.

The aldostools/webman-mod repository allows PlayStation 3 systems to read games and media directly from USB drives formatted with NTFS or exFAT. This capability is achieved by integrating an embedded filesystem driver with custom mounting logic that bridges non-native filesystems to the PS3's XMB interface. Understanding the mechanisms behind webMAN MOD's NTFS and exFAT support reveals how the plugin transparently handles large external libraries without requiring manual file conversion.

Architecture Overview

webMAN MOD organizes its external storage support into three cooperating layers that operate between the USB block device and the PlayStation 3's user interface:

• Filesystem Driver Layer: Provides raw block-level access via the FatFs library (lib/libfatfs-master/source/ff.c), handling sector reads and directory traversal for both NTFS and exFAT volumes.
• Mounting Layer: Detects special path markers (.ntfs[...]) in include/mount/mount_rawiso.h and loads the rawsecISO plugin to create virtual /dev_bdvd devices.
• Content Scanning Layer: The prepNTFS function in include/scan/prepntfs.h walks the directory tree, builds cache files, and injects discovered ISOs into the game list.

These components work together to present NTFS and exFAT drives as native storage, enabling direct launching of PS3ISO, PSXISO, PS2ISO, PSPISO, BDISO, and DVDISO files.

The FatFs Filesystem Driver

At the core of webMAN MOD's external storage capability lies a customized fork of ChaN's FatFs library located in lib/libfatfs-master. This driver operates entirely in user space and provides the foundation for both NTFS and exFAT compatibility.

Configuration and Compilation

The driver is compiled with specific options defined in ffconf.h to enable modern filesystem features:

#define FF_FS_EXFAT      1   // Enable exFAT support
#define FF_USE_LFN       3   // Enable long-file-name support (required for NTFS)

The FF_USE_LFN setting is critical because NTFS relies on long filenames, while FF_FS_EXFAT allows the driver to handle the 64-bit allocation table structure used by modern external drives.

Volume Detection and Sector Access

When a USB device is attached, the driver reads the Volume Boot Record (VBR) to determine the filesystem type. The implementation in lib/libfatfs-master/source/ff.c identifies exFAT volumes by checking for the signature "EXFAT " at offset 3 in the boot sector:

// Detection of exFAT through signature (ff.c L3312-L3314)
if (memcmp(fs->win + BS_FilSysType, "EXFAT   ", 8) == 0) {
    // Handle exFAT-specific initialization
}

For exFAT volumes, the driver fills the alternative name field with an empty string since exFAT does not support legacy 8.3 short filenames (fno->altname). The driver then uses sector-level routines (read, write, sync) to perform block operations on the underlying USB storage.

Path Detection and Mounting Mechanism

webMAN MOD identifies NTFS/exFAT content through a special naming convention rather than traditional mount points. This approach allows the plugin to intercept file access requests and redirect them through the appropriate driver.

Recognizing NTFS Path Markers

When a user selects a game from the XMB, the path is analyzed in include/mount/mount_rawiso.h for the .ntfs[ substring:

char *ntfs_ext = strstr(_path, ".ntfs[");
if (ntfs_ext) {
    set_mount_type(ntfs_ext);  // Set internal mount flag
    
    // Load rawseciso.sprx if available
    const char *rawseciso_sprx[] = {
        WM_RES_PATH "/raw_iso.sprx",
        VSH_MODULE_DIR "raw_iso.sprx",
        WMTMP "/res/sman.ntf"
    };
}

This pattern (e.g., mygame.ntfs[PS3ISO]) indicates that the file resides on an external NTFS or exFAT volume and requires special handling.

rawsecISO Plugin Loading

If the USE_INTERNAL_NTFS_PLUGIN flag is compiled, webMAN MOD spawns a PPU thread (rawseciso_thread) that loads the raw_iso.sprx plugin. This thread performs the following sequence:

1. Permission Handling: Changes file permissions (chmod) to ensure read access to the source file.
2. Buffer Allocation: Allocates a 64 KB buffer and reads the ISO header via read_file.
3. Virtual Device Creation: Passes the file descriptor to cobra_load_vsh_plugin and waits for /dev_bdvd to appear using wait_for("/dev_bdvd", 3).

Once the virtual BDVD device is ready, the system treats the NTFS-hosted ISO as if it were a physical disc in the Blu-ray drive.

Content Scanning with prepNTFS

The prepNTFS system eliminates the need for external tools like prepISO by scanning NTFS/exFAT volumes directly from within webMAN MOD. The entry point is the prepNTFS(u8 clear) function defined in include/scan/prepntfs.h.

Directory Traversal and ISO Detection

The scanner uses FatFs APIs to enumerate contents without mounting the filesystem through the operating system:

static int prepNTFS(u8 clear) {
    DIR dir;
    FILINFO fno;
    
    f_opendir(&dir, "/dev_usb000");
    while (f_readdir(&dir, &fno) == FR_OK && fno.fname[0]) {
        if (strstr(fno.fname, ".iso") || strstr(fno.fname, ".ntfs[")) {
            // Process PS3ISO, PSXISO, PS2ISO, PSPISO entries
            add_to_cache(fno.fname);
        }
    }
    f_closedir(&dir);
    return 0;
}

The function specifically looks for files ending with extensions like .ntfs[PS3ISO], .ntfs[PSXISO], or the "fake ISO" pattern .ntfs[BDFILE] created by IRISMAN or prepISO tools.

Cache Generation and UI Integration

For each valid ISO discovered, prepNTFS generates entries in /dev_hdd0/tmp/wm_cache. This cache file allows the XMB to display games instantly without rescanning the drive. The scanner also handles automatic copying of PS2 and PSP ISOs to /dev_hdd0 for improved playback performance (copy_ps2iso_to_hdd0).

The scanning routine triggers from multiple locations:

• During manual refreshes via include/cmd/refresh.h (ngames = prepNTFS(clear_ntfs);)
• When the game list UI encounters NTFS entries (include/scan/games_xml.h)

Because prepNTFS runs on the dedicated PPU thread created by rawseciso_thread, it processes large external drives without blocking the main interface.

Configuration Flags and Build Options

Users control NTFS/exFAT support through a configuration flag stored in the global settings structure (include/init/wm_config.h):

u8 ntfs;    // 0 = use legacy prepISO, 1 = enable internal prepNTFS

This boolean is exposed in the webMAN MOD setup page (include/setup.h) and persisted to /dev_hdd0/tmp/wm_config.bin. When webman_config->ntfs is enabled, all scanning and mounting logic becomes active. Disabling the flag forces the system to rely on the legacy prepISO workflow requiring external PC-based tools.

Summary

• FatFs Driver: The lib/libfatfs-master/source/ff.c implementation provides block-level NTFS and exFAT access with long filename support enabled via FF_USE_LFN.
• Path Detection: The mount_rawiso.h module recognizes .ntfs[ path markers and spawns the rawseciso_thread to load ISOs through the raw_iso.sprx plugin.
• Virtual Mounting: Successfully parsed paths result in virtual /dev_bdvd devices that the PS3 system treats as physical discs.
• Content Caching: The prepNTFS function scans external volumes using f_opendir and f_readdir, caching results to /dev_hdd0/tmp/wm_cache for instant XMB display.
• Optional Copying: PS2 and PSP ISOs can be automatically copied to the internal HDD for performance optimization during the scan process.

Frequently Asked Questions

How does webMAN MOD distinguish between NTFS and exFAT volumes?

The FatFs driver in lib/libfatfs-master/source/ff.c reads the Volume Boot Record and checks for the "EXFAT " signature at specific offsets to identify exFAT filesystems. For NTFS volumes (treated as FAT with long filename extensions), the driver relies on the FF_USE_LFN configuration and path markers rather than filesystem-specific signatures.

What is the purpose of the .ntfs[ filename suffix?

The .ntfs[ suffix (e.g., game.ntfs[PS3ISO]) serves as a metadata marker that tells webMAN MOD's mounting logic in include/mount/mount_rawiso.h to route the file through the rawsecISO plugin. This convention allows the system to identify external storage content without requiring native filesystem mounting support from the PlayStation 3 OS.

Can webMAN MOD write to NTFS or exFAT drives, or is it read-only?

The current implementation primarily focuses on read operations for launching ISO files. The FatFs driver includes write capabilities (f_write, f_sync), but webMAN MOD's integration emphasizes reading game data and generating cache files on the internal HDD (/dev_hdd0/tmp/). Write operations are generally limited to internal storage for configuration and cache management.

Why does webMAN MOD copy some ISOs to the internal HDD automatically?

The prepNTFS scanner in include/scan/prepntfs.h automatically copies PS2 and PSP ISOs to /dev_hdd0 because these systems require faster access speeds than USB 2.0 can provide for smooth emulation. This behavior is handled during the scanning phase to ensure compatible playback performance while keeping the original files archived on the external NTFS or exFAT drive.

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