/**
 * Copyright (c) 2011-2025 Bill Greiman
 * This file is part of the SdFat library for SD memory cards.
 *
 * MIT License
 *
 * 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
/**
 * \file
 * \brief Common cache code for exFAT and FAT.
 */
#include "FsBlockDevice.h"
#include "SysCall.h"
/**
 * \class FsCache
 * \brief Sector cache.
 */
class FsCache
{
  public:
    /** Cached sector is dirty */
    static const uint8_t CACHE_STATUS_DIRTY = 1;
    /** Cashed sector is FAT entry and must be mirrored in second FAT. */
    static const uint8_t CACHE_STATUS_MIRROR_FAT = 2;
    /** Cache sector status bits */
    static const uint8_t CACHE_STATUS_MASK = CACHE_STATUS_DIRTY | CACHE_STATUS_MIRROR_FAT;
    /** Sync existing sector but do not read new sector. */
    static const uint8_t CACHE_OPTION_NO_READ = 4;
    /** Cache sector for read. */
    static const uint8_t CACHE_FOR_READ = 0;
    /** Cache sector for write. */
    static const uint8_t CACHE_FOR_WRITE = CACHE_STATUS_DIRTY;
    /** Reserve cache sector for write - do not read from sector device. */
    static const uint8_t CACHE_RESERVE_FOR_WRITE = CACHE_STATUS_DIRTY | CACHE_OPTION_NO_READ;
    //----------------------------------------------------------------------------
    /** Constructor. */
    FsCache()
    {
        init(nullptr);
    } // cppcheck-suppress uninitMemberVar
    /** \return Cache buffer address. */
    uint8_t *cacheBuffer()
    {
        return m_buffer;
    }
    /**
     * Cache safe read of a sector.
     *
     * \param[in] sector Logical sector to be read.
     * \param[out] dst Pointer to the location that will receive the data.
     * \return true for success or false for failure.
     */
    bool cacheSafeRead(Sector_t sector, uint8_t *dst)
    {
        if (isCached(sector))
        {
            memcpy(dst, m_buffer, 512);
            return true;
        }
        return m_blockDev->readSector(sector, dst);
    }
    /**
     * Cache safe read of multiple sectors.
     *
     * \param[in] sector Logical sector to be read.
     * \param[in] count Number of sectors to be read.
     * \param[out] dst Pointer to the location that will receive the data.
     * \return true for success or false for failure.
     */
    bool cacheSafeRead(Sector_t sector, uint8_t *dst, size_t count)
    {
        if (isCached(sector, count) && !sync())
        {
            return false;
        }
        return m_blockDev->readSectors(sector, dst, count);
    }
    /**
     * Cache safe write of a sectors.
     *
     * \param[in] sector Logical sector to be written.
     * \param[in] src Pointer to the location of the data to be written.
     * \return true for success or false for failure.
     */
    bool cacheSafeWrite(Sector_t sector, const uint8_t *src)
    {
        if (isCached(sector))
        {
            invalidate();
        }
        return m_blockDev->writeSector(sector, src);
    }
    /**
     * Cache safe write of multiple sectors.
     *
     * \param[in] sector Logical sector to be written.
     * \param[in] src Pointer to the location of the data to be written.
     * \param[in] count Number of sectors to be written.
     * \return true for success or false for failure.
     */
    bool cacheSafeWrite(Sector_t sector, const uint8_t *src, size_t count)
    {
        if (isCached(sector, count))
        {
            invalidate();
        }
        return m_blockDev->writeSectors(sector, src, count);
    }
    /** \return Clear the cache and returns a pointer to the cache. */
    uint8_t *clear()
    {
        if (isDirty() && !sync())
        {
            return nullptr;
        }
        invalidate();
        return m_buffer;
    }
    /** Set current sector dirty. */
    void dirty()
    {
        m_status |= CACHE_STATUS_DIRTY;
    }
    /** Initialize the cache.
     * \param[in] blockDev Block device for this cache.
     */
    void init(FsBlockDevice *blockDev)
    {
        m_blockDev = blockDev;
        invalidate();
    }
    /** Invalidate current cache sector. */
    void invalidate()
    {
        m_status = 0;
        m_sector = 0XFFFFFFFF;
    }
    /** Check if a sector is in the cache.
     * \param[in] sector Sector to checked.
     * \return true if the sector is cached.
     */
    bool isCached(Sector_t sector) const
    {
        return sector == m_sector;
    }
    /** Check if the cache contains a sector from a range.
     * \param[in] sector Start sector of the range.
     * \param[in] count Number of sectors in the range.
     * \return true if a sector in the range is cached.
     */
    bool isCached(Sector_t sector, size_t count)
    {
        return sector <= m_sector && m_sector < (sector + count);
    }
    /** \return dirty status */
    bool isDirty()
    {
        return m_status & CACHE_STATUS_DIRTY;
    }
    /** Prepare cache to access sector.
     * \param[in] sector Sector to read.
     * \param[in] option mode for cached sector.
     * \return Address of cached sector.
     */
    uint8_t *prepare(Sector_t sector, uint8_t option);
    /** \return Logical sector number for cached sector. */
    Sector_t sector()
    {
        return m_sector;
    }
    /** Set the offset to the second FAT for mirroring.
     * \param[in] offset Sector offset to second FAT.
     */
    void setMirrorOffset(uint32_t offset)
    {
        m_mirrorOffset = offset;
    }
    /** Write current sector if dirty.
     * \return true for success or false for failure.
     */
    bool sync();

  private:
    uint8_t m_status;
    FsBlockDevice *m_blockDev;
    Sector_t m_sector;
    uint32_t m_mirrorOffset;
    uint8_t m_buffer[512] __attribute__((aligned(4)));
};
