memory-card-filesystem.hh

Go to the documentation of this file.

/*
 
MIT License
 
Copyright (c) 2026 PCSX-Redux authors
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
 
*/
 
#pragma once
 
#include <EASTL/functional.h>
#include <stdint.h>
 
#include "psyqo/memory-card.hh"
 
namespace psyqo {
 
class GPU;
 
class MemoryCardFileSystem {
  public:
    struct Icon {
        uint8_t frameCount;      // 1..3
        uint16_t clut[16];       // 16-colour palette, BGR555
        uint8_t pixels[3][128];  // up to 3 frames of 16x16 4bpp
    };
 
    struct FileEntry {
        char name[21];          // null-terminated Sony filename
        uint16_t sizeInBlocks;  // 1..15
        uint8_t firstBlock;     // 1..15
    };
 
    struct FileInfo {
        uint8_t title[65];  // 64-byte Shift-JIS title field + NUL
        Icon icon;          // palette + up to 3 animation frames
    };
 
    explicit MemoryCardFileSystem(MemoryCard &card) : m_card(card) {}
 
    [[nodiscard]] bool isIdle() const { return !m_busy; }
 
    using Error = MemoryCard::Error;
    using Port = MemoryCard::Port;
 
    // -- Asynchronous operations (the callback basis) -----------------------
    // Each starts a transaction and returns immediately; `callback` fires from
    // the main loop, during GPU pumping, once the transaction completes. Only
    // one may be in flight at a time (asserts idle).
 
    void getCardState(Port port, eastl::function<void(Error)> &&callback);
 
    void format(Port port, eastl::function<void(Error)> &&callback);
 
    void getFreeBlockCount(Port port, uint32_t *outFreeBlocks, eastl::function<void(Error)> &&callback);
 
    void listFiles(Port port, FileEntry *out, uint32_t maxEntries, uint32_t *outCount,
                   eastl::function<void(Error)> &&callback);
 
    void fileExists(Port port, const char *name, bool *outExists, eastl::function<void(Error)> &&callback);
 
    void readFile(Port port, const char *name, void *buffer, uint32_t maxLen, uint32_t *outLen,
                  eastl::function<void(Error)> &&callback);
 
    void readFileInfo(Port port, const char *name, FileInfo *out, eastl::function<void(Error)> &&callback);
 
    void writeFile(Port port, const char *name, const char *title, const Icon &icon, const void *data, uint32_t dataLen,
                   eastl::function<void(Error)> &&callback);
 
    void deleteFile(Port port, const char *name, eastl::function<void(Error)> &&callback);
 
    // -- Blocking variants --------------------------------------------------
    // These run the same transaction but pump the GPU until it finishes and
    // return the error directly. They still take a few hundred milliseconds for
    // a non-trivial payload, so they are best used at a deliberate save point.
    // Calling one from inside a queued callback, such as another operation's
    // completion callback, pumps the callback queue from within the pump; this
    // is supported, and the remaining queued callbacks still run once each, in
    // order.
 
    Error getCardStateBlocking(GPU &gpu, Port port);
    Error formatBlocking(GPU &gpu, Port port);
    Error getFreeBlockCountBlocking(GPU &gpu, Port port, uint32_t *outFreeBlocks);
    Error listFilesBlocking(GPU &gpu, Port port, FileEntry *out, uint32_t maxEntries, uint32_t *outCount);
    Error fileExistsBlocking(GPU &gpu, Port port, const char *name, bool *outExists);
    Error readFileBlocking(GPU &gpu, Port port, const char *name, void *buffer, uint32_t maxLen, uint32_t *outLen);
    Error readFileInfoBlocking(GPU &gpu, Port port, const char *name, FileInfo *out);
    Error writeFileBlocking(GPU &gpu, Port port, const char *name, const char *title, const Icon &icon,
                            const void *data, uint32_t dataLen);
    Error deleteFileBlocking(GPU &gpu, Port port, const char *name);
 
  private:
    // A 4-byte aligned 128-byte frame buffer.
    struct Frame {
        alignas(4) uint8_t bytes[128];
    };
 
    // Directory allocation states (low byte of the 32-bit state word). The high
    // nibble separates in-use (0x5x) from available (0xax); the low nibble is
    // the block's position in its chain, preserved across deletion so a deleted
    // chain stays recoverable.
    static constexpr uint8_t c_stateFirst = 0x51;          // in use: first or only block
    static constexpr uint8_t c_stateMiddle = 0x52;         // in use: middle block
    static constexpr uint8_t c_stateLast = 0x53;           // in use: last block
    static constexpr uint8_t c_stateFree = 0xa0;           // available: never allocated
    static constexpr uint8_t c_stateDeletedFirst = 0xa1;   // available: a deleted first block
    static constexpr uint8_t c_stateDeletedMiddle = 0xa2;  // available: a deleted middle block
    static constexpr uint8_t c_stateDeletedLast = 0xa3;    // available: a deleted last block
 
    // Directory entry field offsets.
    static constexpr uint32_t c_offAlloc = 0x00;
    static constexpr uint32_t c_offSize = 0x04;
    static constexpr uint32_t c_offNext = 0x08;
    static constexpr uint32_t c_offName = 0x0a;
    static constexpr uint32_t c_offChecksum = 0x7f;
    static constexpr uint32_t c_maxNameLength = 20;
 
    static uint8_t frameChecksum(const uint8_t *frame);
    static void finishDirEntry(uint8_t *entry);
    // Marks an in-use block (0x5x) deleted, keeping its chain position (0x5x ->
    // 0xax) and so its links, so the deleted chain stays recoverable.
    static uint8_t deletedState(uint8_t inUse) { return static_cast<uint8_t>((inUse & 0x0f) | 0xa0); }
    static bool nameMatches(const uint8_t *entry, const char *name);
    static bool findFirstBlock(const Frame *dir15, const char *name, int *outBlock);
    // The set of blocks (bit (slot + 1)) reachable from a valid first-block
    // head. Anything else - free, deleted, or an orphaned middle/last block with
    // no head - is available for allocation.
    static uint16_t reachableBlocks(const Frame *dir15);
 
    // -- Asynchronous transaction engine -----------------------------------
    // The operation in flight, and where in it we are. Each device sector
    // completion advances the machine by exactly one sector transfer.
    enum class Op : uint8_t {
        None,
        GetCardState,
        Format,
        GetFreeBlockCount,
        ListFiles,
        FileExists,
        ReadFile,
        ReadInfo,
        WriteFile,
        DeleteFile,
    };
    enum class Phase : uint8_t {
        Fail,       // m_result is set; finish on the next tick
        Header,     // read sector 0, validate "MC"
        Probe,      // read sector m_probeSector, compare it with sector 0
        ReadDir,    // read the 15 directory frames (m_idx = 0..14)
        ReadTitle,  // read a file's first frame to size its header (readFile)
        ReadData,   // read a file's payload frames (readFile)
        ReadInfo,   // read a file's title + icon frames (readFileInfo)
        WriteData,  // write title/icon/payload frames (writeFile)
        WriteDir,   // commit the dirty directory frames (write/delete)
        Format,     // zero the probe sectors, then write the format frames (m_idx = 0..66)
    };
    enum class StepResult : uint8_t { Continue, Done };
 
    void begin(Op op, Port port, eastl::function<void(Error)> &&callback);
    Error runBlocking(GPU &gpu);
    // Issues exactly one asynchronous device sector transfer for the current
    // phase, or finishes the transaction if the current phase has no transfer
    // left to do.
    void issueOrFinish();
    // The device's per-sector completion callback: consumes the transfer's
    // result, advances the per-operation state machine, then chains the next
    // transfer (or finishes).
    void onSectorDone(Error error);
    StepResult afterReadDir();
    void finish(Error error);
 
    MemoryCard &m_card;
 
    // engine state
    bool m_busy = false;
    bool m_lockHeld = false;
    eastl::function<void(Error)> m_callback;
    Error m_result = Error::OK;
    Op m_op = Op::None;
    Phase m_phase = Phase::Fail;
    Port m_port = Port::Port0;
    uint32_t m_idx = 0;  // step within the current phase
 
    // working buffers / per-operation state
    Frame m_dir[15];
    Frame m_scratch;
    Frame m_probe;
    // The card's size in blocks, as measured by the Probe phase: 16, or the
    // block where sector 0 first repeats on a smaller card.
    uint32_t m_cardBlocks = 16;
    uint16_t m_probeSector = 0;
    uint8_t m_chain[16];
    uint32_t m_chainLen = 0;
    uint32_t m_headerFrames = 0;
    uint32_t m_blocksNeeded = 0;
    uint32_t m_iconFrames = 0;
    bool m_dirty[15] = {};
    // The directory slots to commit, in the order they must be written: for a
    // create the file's head (the 0x51 first block) is written last; for a
    // delete its head (cut to 0xa1) is written first. So a power loss mid-commit
    // can only orphan tail blocks, never leave a referenced file pointing at a
    // half-written chain.
    uint8_t m_writeOrder[15] = {};
    uint32_t m_writeOrderLen = 0;
    uint32_t m_dataOffset = 0;
    uint32_t m_written = 0;
    uint32_t m_blockIdx = 0;      // current block within the chain
    uint32_t m_frameInBlock = 0;  // current frame within the current block
 
    // saved operation arguments
    const char *m_name = nullptr;
    const char *m_title = nullptr;
    void *m_readBuffer = nullptr;
    const void *m_writeData = nullptr;
    uint32_t m_dataLen = 0;
    uint32_t m_maxLen = 0;
    uint32_t *m_outLen = nullptr;
    uint32_t *m_outFreeBlocks = nullptr;
    uint32_t *m_outCount = nullptr;
    bool *m_outExists = nullptr;
    FileEntry *m_outEntries = nullptr;
    FileInfo *m_outInfo = nullptr;
    uint32_t m_maxEntries = 0;
    Icon m_icon = {};
};
 
}  // namespace psyqo