memory-card.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 <coroutine>
 
#include "psyqo/task.hh"
 
namespace psyqo {
 
class GPU;
 
class MemoryCard {
  public:
    enum class Error : uint8_t {
        OK = 0,             // No error.
        NoCard,             // No card present / no acknowledge on the bus.
        NotFormatted,       // Card is present but is not a valid Sony card.
        BadChecksum,        // A frame checksum did not match.
        BadSector,          // The card reported a bad / out of range sector.
        Timeout,            // The card stopped acknowledging mid-transfer.
        Unconnected,        // The port could not be selected.
        ProtocolError,      // Unexpected response byte from the card.
        DirectoryFull,      // No free directory entry for a new file.
        OutOfSpace,         // Not enough free blocks for a file.
        FileNotFound,       // The requested file does not exist.
        FileExists,         // A file with that name already exists.
        NameTooLong,        // The filename exceeds 20 characters.
        FileTooLarge,       // The payload would not fit in 15 blocks.
        SerializeOverflow,  // The serialized payload exceeded the buffer.
        BadData,            // The payload header / structure is corrupt.
        BadPort,            // The port argument is invalid.
    };
 
    enum class Port : unsigned { Port0 = 0, Port1 = 1 };
 
    // Geometry constants.
    static constexpr uint32_t c_sectorSize = 128;       // bytes per sector / frame
    static constexpr uint32_t c_sectorCount = 1024;     // sectors per card
    static constexpr uint32_t c_blockSize = 8192;       // bytes per block
    static constexpr uint32_t c_blockCount = 16;        // blocks per card
    static constexpr uint32_t c_sectorsPerBlock = 64;   // sectors per block
 
    static constexpr uint32_t sectorSize() { return c_sectorSize; }
    static constexpr uint32_t sectorCount() { return c_sectorCount; }
    static constexpr uint32_t blockSize() { return c_blockSize; }
    static constexpr uint32_t blockCount() { return c_blockCount; }
 
    static const char *errorMessage(Error error);
 
    void prepare();
 
    Error readSectorBlocking(Port port, uint16_t sector, void *buffer);
 
    Error writeSectorBlocking(Port port, uint16_t sector, const void *buffer);
 
    Error probeBlocking(Port port);
 
    // --- Callback variants -------------------------------------------------
    void readSector(Port port, uint16_t sector, void *buffer, eastl::function<void(Error)> &&callback);
    void writeSector(Port port, uint16_t sector, const void *buffer, eastl::function<void(Error)> &&callback);
 
    // --- TaskQueue schedulers ---------------------------------------------
    TaskQueue::Task scheduleReadSector(Port port, uint16_t sector, void *buffer, Error *resultOut);
    TaskQueue::Task scheduleWriteSector(Port port, uint16_t sector, const void *buffer, Error *resultOut);
 
    // --- Coroutine-friendly awaiters --------------------------------------
    struct ReadSectorAwaiter {
        ReadSectorAwaiter(MemoryCard &device, Port port, uint16_t sector, void *buffer)
            : m_device(device), m_port(port), m_sector(sector), m_buffer(buffer) {}
        bool await_ready() const { return false; }
        template <typename U>
        void await_suspend(std::coroutine_handle<U> handle) {
            m_device.readSector(m_port, m_sector, m_buffer, [handle, this](Error result) {
                m_result = result;
                handle.resume();
            });
        }
        Error await_resume() { return m_result; }
 
      private:
        MemoryCard &m_device;
        Port m_port;
        uint16_t m_sector;
        void *m_buffer;
        Error m_result = Error::OK;
    };
 
    struct WriteSectorAwaiter {
        WriteSectorAwaiter(MemoryCard &device, Port port, uint16_t sector, const void *buffer)
            : m_device(device), m_port(port), m_sector(sector), m_buffer(buffer) {}
        bool await_ready() const { return false; }
        template <typename U>
        void await_suspend(std::coroutine_handle<U> handle) {
            m_device.writeSector(m_port, m_sector, m_buffer, [handle, this](Error result) {
                m_result = result;
                handle.resume();
            });
        }
        Error await_resume() { return m_result; }
 
      private:
        MemoryCard &m_device;
        Port m_port;
        uint16_t m_sector;
        const void *m_buffer;
        Error m_result = Error::OK;
    };
 
    ReadSectorAwaiter readSector(Port port, uint16_t sector, void *buffer) { return {*this, port, sector, buffer}; }
    WriteSectorAwaiter writeSector(Port port, uint16_t sector, const void *buffer) {
        return {*this, port, sector, buffer};
    }
 
  private:
    // -- Transport selection -----------------------------------------------
    // The driver has two interchangeable transports for a single sector:
    //   * an interrupt-driven state machine (the default, modelled on the
    //     retail BIOS / openbios sio0 driver), and
    //   * a synchronous busy-polled transport (kept as a proven fallback).
    // If the IRQ transport ever misbehaves on a particular setup, flip this to
    // false to fall back to polling without touching anything else.
    static constexpr bool c_useIrq = true;
 
    // -- Retry / dispatch layer --------------------------------------------
    Error singleSectorRead(Port port, uint16_t sector, uint8_t *out);
    Error singleSectorWrite(Port port, uint16_t sector, const uint8_t *in);
    Error readSectorRetried(Port port, uint16_t sector, uint8_t *out);
    Error writeSectorRetried(Port port, uint16_t sector, const uint8_t *in);
    static bool isTransient(Error error);
 
    // -- Interrupt-driven transport ----------------------------------------
    enum class Action : uint8_t { None, Read, Write };
    enum class StepResult { Continue, Done };
 
    void installIrqHandler();
    void irq();  // entered on each SIO0 (controller) acknowledge interrupt
    void startTransfer(Action action, Port port, uint16_t sector, void *readBuf, const void *writeBuf);
    void finishTransfer(Error result);
    StepResult readStep();
    StepResult writeStep();
    uint8_t exchangeByte(uint8_t out);  // openbios-style: read previous, send next, ack
    Error irqTransferBlocking(Action action, Port port, uint16_t sector, void *readBuf, const void *writeBuf);
    // Asynchronous whole-transfer retry, mirroring the blocking *Retried path:
    // re-issues a transient-failed callback transfer up to c_maxAttempts times
    // before delivering the result. With the first-byte select timing corrected
    // this is a safeguard against the occasional genuine bus glitch, not the
    // primary mechanism, so it should rarely fire.
    void startAsyncAttempt(Action action, Port port, uint16_t sector, void *readBuf, const void *writeBuf);
    void onAsyncAttemptDone(Error result);
    static uint16_t portMask(Port port);
 
    // -- Polled transport (fallback) ---------------------------------------
    Error doReadSector(Port port, uint16_t sector, uint8_t *out);
    Error doWriteSector(Port port, uint16_t sector, const uint8_t *in);
    void selectPort(Port port);
    void deselect();
    void flushRxBuffer();
    uint8_t transceive(uint8_t dataOut);
    bool waitAck(uint32_t timeout);
 
    // Hold the bus deselected (/CS high) for the inter-transaction recovery
    // window before selecting the port for a fresh transfer. Shared by both
    // transports (startTransfer and selectPort).
    void recoverBeforeSelect();
 
    static void busyLoop(unsigned delay) {
        unsigned cycles = 0;
        while (++cycles < delay) asm("");
    }
 
    // -- Interrupt-driven state --------------------------------------------
    volatile Action m_action = Action::None;
    int m_step = 0;
    Port m_port = Port::Port0;
    uint16_t m_sector = 0;
    uint8_t *m_readBuffer = nullptr;
    const uint8_t *m_writeBuffer = nullptr;
    uint8_t m_runningChecksum = 0;
    uint8_t m_cardChecksum = 0;
    volatile bool m_done = false;
    volatile Error m_result = Error::OK;
    bool m_blocking = false;
    eastl::function<void(Error)> m_callback;
    uint32_t m_event = 0;
    // Async retry bookkeeping: the user's callback is preserved in m_userCallback
    // across the internal retries, while m_callback is reused to drive each attempt.
    eastl::function<void(Error)> m_userCallback;
    Action m_retryAction = Action::None;
    unsigned m_attempt = 0;
 
    // The first (addressing) byte uses this timeout to detect a missing card.
    // It is the one value that is deliberately generous: a present-but-slow
    // real card can take a while to acknowledge the very first byte after the
    // port is selected, and too short a value here is what makes a good card
    // spuriously report "no card". It does not affect mid-transfer timing
    // (a present card acknowledges the first byte well before the limit).
    static constexpr uint32_t c_ackTimeoutShort = 0x4000;
    // Sony cards introduce a ~31000 cycle gap before the acknowledge that
    // follows the seventh byte of a read; the long timeout covers it with a
    // comfortable margin and is also used as the general mid-transfer timeout.
    static constexpr uint32_t c_ackTimeoutLong = 0x40000;
    static constexpr uint32_t c_ackHighTimeout = 0x4000;
    // Settle time after asserting the port select, before the first clock.
    static constexpr unsigned c_selectDelay = 100;
    // Recovery window held with the bus deselected (/CS high) between sector
    // transactions. The retail BIOS gets this for free by pacing each sector on
    // a vblank boundary (~16ms apart); we issue transactions back-to-back, so a
    // slow third-party card can be reselected before it has finished recovering
    // from the previous read and then serve stale (wrong-but-valid) sector data.
    // busyLoop(100) is ~23us, so ~70000 approximates the BIOS's ~16ms. Tune down
    // toward the smallest reliable value once a working floor is found on hardware.
    static constexpr unsigned c_interTransactionDelay = 70000;
    // How many times a whole-sector transient failure is retried.
    static constexpr unsigned c_maxAttempts = 3;
    // Spin-loop bound for the blocking IRQ path: large enough never to trip
    // during a normal ~8ms transfer, small enough to bail on a dead bus.
    static constexpr uint32_t c_irqWatchdog = 0x800000;
};
 
}  // namespace psyqo