feat(favourites): APA-HDD VCD favourites -- launch PS1 games off the internal HDD from Favourites

Completes VCD-favourite coverage: the APA-formatted internal HDD (HDD_MODE) now
implements itemLaunchVcd, so its PS1/.VCD games can be favourited and launched
from the Favourites tab like every other device. (Previously deferred -- R3 was a
no-op there.)

The challenge is that the HDD VCD list (hddVcdGames + the index-parallel
hddVcdParts, which records each game's owning __.POPS partition) is only built
while the HDD page is in its VCD view, so from the Favourites tab the owning
partition for a given name may be unknown. hddLaunchVcd resolves it by name:

- hddDoLaunchVcd() is the existing in-view POPSTARTER handoff, extracted verbatim
  (selector + hdd0:<part>: target built on stack BEFORE deinit frees the list);
  the in-view branch now calls it too -- one code path, behaviour-identical.
- hddLaunchVcd() finds the name in hddVcdGames; the WARM path (visited the HDD VCD
  view this session -> the list persists across the L3 switch) needs no rescan. The
  COLD path (re)scans via hddBuildVcdGameList -- the SAME single-pfs0:-slot partition
  walk the VCD view uses (mounts each __.POPS on pfs0:, scans, restores pfs0:); it
  never opens a 2nd pfs slot, so the documented pfs1: single-slot wedge can't fire.

FREEZE GUARD (adversarial review caught this): the cold rescan runs on the launch
(main) thread, where -- unlike the in-view rescan (IO thread, gated on no pending
art/IO) -- the cache worker can still hold an open fd reading a cover from pfs0:.
Umounting pfs0: under it is the HDD-freeze class. So hddLaunchVcd quiesces the art +
IO workers (cacheAbortMmceImageLoadsTimed + cacheCancelPendingImageLoadsTimed +
ioBlockOps) before the rescan, exactly as deinit() does, then restores. Verified
no use-after-free (name/part copied to stack before deinit) and graceful failure
when the HDD isn't mounted (scan returns 0 -> "POPSTARTER not found", no crash).

favResolve/favGetConfig/favGetImage already cover HDD generically via itemGetPrefix
(gHDDPrefix=pfs0:OPL/): HDD VCD favourites get the SAME pfs0:OPL/ART cover art as
the HDD VCD view + the PS1 #DiscType badge. The opl.c itemLaunchVcd==NULL guard
stays as a future-proof backstop. docs/VCD.md updated (caveat removed).

REMAINING: HW validation (HDD POPSTARTER launch + the cold-path rescan; no emulator
coverage for the HDD POPSTARTER path).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NathanNeurotic

docs/VCD.md

@@ -44,10 +44,10 @@ A VCD favourite launches through POPSTARTER straight from the Favourites tab —
 source device page is currently showing its disc list — and carries its PS1 cover art and
 disc badge with it.
 
-This works for VCDs on **USB, MX4SIO, the internal exFAT HDD, SMB, and MMCE**. PS1 favourites
-for games on an **APA-formatted internal HDD** aren't supported yet (R3 there does nothing on a
-VCD), since that layout keeps each PS1 game on its own `__.POPS` partition; the common internal
-exFAT HDD is covered.
+This works on **every device with a VCD view** — USB, MX4SIO, the internal exFAT HDD, SMB, MMCE,
+and the **APA-formatted internal HDD**. (On the APA HDD each PS1 game lives on its own `__.POPS`
+partition, so opening one of its VCD favourites re-scans those partitions to find the game — the
+first launch may take a moment.)
 
 ## 3. How PS1 games launch (POPSTARTER only)
 

include/iosupport.h

@@ -156,10 +156,9 @@ typedef struct _item_list_t
     int (*itemIconId)(item_list_t *itemList);
 
     /// Launch a PS1/.VCD entry BY NAME via POPSTARTER, independent of the device's current ISO/VCD
-    /// view. NULL for devices without a VCD view (and for the APA HDD, whose __.POPS partition model
-    /// is not name-resolvable here). Used by the Favourites tab to launch a VCD favourite while its
-    /// source device page may be in ISO view -- the id-based itemLaunch's VCD branch is gated on the
-    /// device being live in VCD view, which the Favourites tab cannot guarantee.
+    /// view. NULL for devices without a VCD view. Used by the Favourites tab to launch a VCD favourite
+    /// while its source device page may be in ISO view -- the id-based itemLaunch's VCD branch is gated
+    /// on the device being live in VCD view, which the Favourites tab cannot guarantee.
     void (*itemLaunchVcd)(item_list_t *itemList, const char *vcdName, config_set_t *configSet);
 } item_list_t;
 

src/favsupport.c

@@ -344,9 +344,8 @@ static item_list_t *favResolve(int mode, int id, const char *text, int isVcd, in
     // ISO view right now (its submenu/games array holds discs, not VCDs), yet we must still surface +
     // launch the PS1 favourite. So we only need a loaded device that can launch a VCD (itemLaunchVcd
     // != NULL); art/config/launch all key off the stored name + the device's prefix (itemGetPrefix).
-    // A device whose VCD list lives off the browse prefix and provides no itemLaunchVcd (APA HDD __.POPS
-    // partitions) is intentionally skipped here -- the common internal exFAT HDD is a BDM massN: device
-    // and is covered through the BDM branch.
+    // A device that provides no itemLaunchVcd is skipped here -- a future-proof backstop, since every
+    // VCD-capable device (BDM/ETH/MMCE/HDD) implements it today.
     if (isVcd) {
         if (mode >= BDM_MODE && mode <= BDM_MODE_LAST) {
             // Prefer the stored slot; else the first loaded BDM slot (a stick can change slots).

src/hddsupport.c

@@ -9,6 +9,7 @@
 #include "include/themes.h"
 #include "include/textures.h"
 #include "include/ioman.h"
+#include "include/texcache.h" // cache quiesce before the launch-path VCD partition rescan (freeze guard)
 #include "include/system.h"
 #include "include/extern_irx.h"
 #include "include/cheatman.h"
@@ -532,6 +533,68 @@ static void hddRenameGame(item_list_t *itemList, int id, char *newName)
     hddForceUpdate = 1;
 }
 
+// Index of the VCD whose basename matches vcdName in the current hddVcdGames list, or -1.
+static int hddFindVcdByName(const char *vcdName)
+{
+    for (int i = 0; i < hddVcdGameCount; i++) {
+        if (strcmp(hddVcdGames[i].name, vcdName) == 0)
+            return i;
+    }
+    return -1;
+}
+
+// Shared POPSTARTER handoff for an HDD VCD. POPSTARTER's argv[0] is just the VCD name; the owning
+// __.POPS* partition (`part`) is passed OUT OF BAND so POPSTARTER self-mounts it after the IOP reset.
+// Everything is built on stack BEFORE deinit() frees the VCD list. Used by both the in-view menu launch
+// and the Favourites tab (hddLaunchVcd).
+static void hddDoLaunchVcd(item_list_t *itemList, const char *vcdName, const char *part)
+{
+    char vcdElf[256], vcdSelector[320], vcdPart[64];
+
+    if (vcdName == NULL || vcdName[0] == '\0' || !strcmp(vcdName, "POPSTARTER"))
+        return;
+    if (!vcdResolvePopstarter(gHDDPrefix, vcdElf, sizeof(vcdElf))) {
+        guiMsgBox(_l(_STR_POPSTARTER_NOT_FOUND), 0, NULL);
+        return;
+    }
+    snprintf(vcdSelector, sizeof(vcdSelector), "%s.ELF", vcdName); // POPSTARTER's argv[0] = the name
+    snprintf(vcdPart, sizeof(vcdPart), "hdd0:%s:", part);          // self-mount target, hdd0:PART:
+    deinit(UNMOUNT_EXCEPTION, itemList->mode);
+    sysLaunchPopstarter(vcdElf, vcdSelector, vcdPart);
+}
+
+// Launch an HDD PS1/.VCD entry BY NAME -- the Favourites tab's view-independent entry point. The
+// per-game __.POPS* partition lives in hddVcdParts, which is only populated while the HDD page is in
+// its VCD view; from Favourites it may be empty/stale, so (re)scan via the SAME safe partition walk the
+// VCD view uses (hddBuildVcdGameList mounts each __.POPS on pfs0:, scans, restores pfs0: to the default
+// OPL partition) to resolve name -> partition, then hand off exactly as the in-view launch does.
+static void hddLaunchVcd(item_list_t *itemList, const char *vcdName, config_set_t *configSet)
+{
+    if (vcdName == NULL || vcdName[0] == '\0' || !strcmp(vcdName, "POPSTARTER"))
+        return;
+
+    int idx = hddFindVcdByName(vcdName);
+    if (idx < 0) {
+        // Cold path: the per-game __.POPS partition is unknown (hddVcdGames is only built while the HDD
+        // page is in VCD view). hddBuildVcdGameList remounts the single ps2fs slot (pfs0:), and
+        // umounting it while the cache worker holds an open fd reading a cover from pfs0: is the
+        // documented HDD-freeze hazard. The equivalent in-view rescan runs on the IO thread only when no
+        // art/IO is pending (opl.c menuUpdateHook); on the launch path we enforce the same invariant by
+        // quiescing the art + IO workers first, exactly as deinit() does before its own teardown IO.
+        cacheAbortMmceImageLoadsTimed(0);
+        (void)cacheCancelPendingImageLoadsTimed(0);
+        ioBlockOps(1);
+        hddBuildVcdGameList(); // restores pfs0: to the default OPL partition when done
+        ioBlockOps(0);
+        idx = hddFindVcdByName(vcdName);
+    }
+    if (idx < 0) {
+        guiMsgBox(_l(_STR_POPSTARTER_NOT_FOUND), 0, NULL);
+        return;
+    }
+    hddDoLaunchVcd(itemList, hddVcdGames[idx].name, hddVcdParts[idx]);
+}
+
 void hddLaunchGame(item_list_t *itemList, int id, config_set_t *configSet)
 {
     int i, size_irx = 0;
@@ -549,18 +612,7 @@ void hddLaunchGame(item_list_t *itemList, int id, config_set_t *configSet)
     // selector/partition contract is hardware-testable -- POPSLoader proved the shape with a vendored
     // loader; we use the stock ps2sdk loader, the same one the shipping USB/MMCE/SMB VCD launch uses.
     if (gAutoLaunchGame == NULL && vcdViewActive(itemList->mode)) {
-        char vcdName[VCD_NAME_MAX], vcdElf[256], vcdSelector[320], vcdPart[64];
-        snprintf(vcdName, sizeof(vcdName), "%s", hddVcdGames[id].name);
-        if (vcdName[0] == '\0' || !strcmp(vcdName, "POPSTARTER"))
-            return;
-        if (!vcdResolvePopstarter(gHDDPrefix, vcdElf, sizeof(vcdElf))) {
-            guiMsgBox(_l(_STR_POPSTARTER_NOT_FOUND), 0, NULL);
-            return;
-        }
-        snprintf(vcdSelector, sizeof(vcdSelector), "%s.ELF", vcdName);   // POPSTARTER's argv[0] = the name
-        snprintf(vcdPart, sizeof(vcdPart), "hdd0:%s:", hddVcdParts[id]); // self-mount target, hdd0:PART:
-        deinit(UNMOUNT_EXCEPTION, itemList->mode);
-        sysLaunchPopstarter(vcdElf, vcdSelector, vcdPart);
+        hddDoLaunchVcd(itemList, hddVcdGames[id].name, hddVcdParts[id]);
         return;
     }
 
@@ -1029,4 +1081,4 @@ static char *hddGetPrefix(item_list_t *itemList)
 static item_list_t hddGameList = {
     HDD_MODE, 0, 0, MODE_FLAG_COMPAT_DMA, MENU_MIN_INACTIVE_FRAMES, HDD_MODE_UPDATE_DELAY, NULL, NULL, &hddGetTextId, &hddGetPrefix, &hddInit, &hddNeedsUpdate, &hddUpdateGameList,
     &hddGetGameCount, &hddGetGame, &hddGetGameName, &hddGetGameNameLength, &hddGetGameStartup, &hddDeleteGame, &hddRenameGame,
-    &hddLaunchGame, &hddGetConfig, &hddGetImage, &hddCleanUp, &hddShutdown, &hddCheckVMC, &hddGetIconId};
+    &hddLaunchGame, &hddGetConfig, &hddGetImage, &hddCleanUp, &hddShutdown, &hddCheckVMC, &hddGetIconId, &hddLaunchVcd};

src/opl.c

@@ -406,10 +406,11 @@ static void itemExecFav(struct menu_item *curMenu)
         // it resolves + launches as POPSTARTER and lands in the Favourites tab's own VCD view.
         int isVcd = vcdViewActive(support->mode) ? 1 : 0;
         // ...but only on a device whose VCD favourites can actually be resolved/launched later
-        // (itemLaunchVcd present). The APA HDD's __.POPS partition model isn't name-resolvable yet, so
-        // storing a VCD favourite there would be permanently hidden + unlaunchable -- make R3 an honest
-        // no-op (no record, no star, no confirm sound) rather than a misleading "saved". Disc favourites
-        // on the same device are unaffected (isVcd == 0 there).
+        // (itemLaunchVcd present). Storing a VCD favourite on a device without it would leave a
+        // permanently-hidden, unlaunchable record, so make R3 an honest no-op (no record, no star, no
+        // confirm sound) rather than a misleading "saved". Every VCD-capable device (BDM/ETH/MMCE/HDD)
+        // implements itemLaunchVcd today -- this is a future-proof backstop. Disc favourites are
+        // unaffected (isVcd == 0 there).
         if (isVcd && support->itemLaunchVcd == NULL)
             return;
         if (it->favourited) {