Introduce >2GB compatible PR 1424 from fdkekin0

lib/Xtc/Xtc/XtcParser.h

@@ -9,6 +9,8 @@
 
 #include <HalStorage.h>
 
+#include <array>
+#include <cstring>
 #include <functional>
 #include <memory>
 #include <string>
@@ -30,7 +32,7 @@ class XtcParser {
   ~XtcParser();
 
   // File open/close
-  XtcError open(const char* filepath);
+  XtcError open(const char* filepath, const char* cacheDir);
   void close();
   bool isOpen() const { return m_isOpen; }
 
@@ -41,28 +43,14 @@ class XtcParser {
   uint16_t getHeight() const { return m_defaultHeight; }
   uint8_t getBitDepth() const { return m_bitDepth; }  // 1 = XTC/XTG, 2 = XTCH/XTH
 
-  // Page information
-  bool getPageInfo(uint32_t pageIndex, PageInfo& info) const;
+  // Page information - three-tier cache interface
+  bool getPageInfo(uint32_t pageIndex, PageInfo& info);
 
-  /**
-   * Load page bitmap (raw 1-bit data, skipping XTG header)
-   *
-   * @param pageIndex Page index (0-based)
-   * @param buffer Output buffer (caller allocated)
-   * @param bufferSize Buffer size
-   * @return Number of bytes read on success, 0 on failure
-   */
+  // Preload window around specified page (optimize sequential page turns)
+  void prefetchWindow(uint32_t pageIndex);
+
+  // Load page bitmap (unchanged)
   size_t loadPage(uint32_t pageIndex, uint8_t* buffer, size_t bufferSize);
-
-  /**
-   * Streaming page load
-   * Memory-efficient method that reads page data in chunks.
-   *
-   * @param pageIndex Page index
-   * @param callback Callback function to receive data chunks
-   * @param chunkSize Chunk size (default: 1024 bytes)
-   * @return Error code
-   */
   XtcError loadPageStreaming(uint32_t pageIndex,
                              std::function<void(const uint8_t* data, size_t size, size_t offset)> callback,
                              size_t chunkSize = 1024);
@@ -72,7 +60,7 @@ class XtcParser {
   std::string getAuthor() const { return m_author; }
 
   bool hasChapters() const { return m_hasChapters; }
-  const std::vector<ChapterInfo>& getChapters() const { return m_chapters; }
+  const std::vector<ChapterInfo>& getChapters();
 
   // Validation
   static bool isValidXtcFile(const char* filepath);
@@ -82,24 +70,62 @@ class XtcParser {
 
  private:
   FsFile m_file;
+  FsFile m_cacheFile;
   bool m_isOpen;
   XtcHeader m_header;
-  std::vector<PageInfo> m_pageTable;
-  std::vector<ChapterInfo> m_chapters;
+  std::string m_cacheDir;
+  std::string m_cacheFilePath;
+  std::string m_originalPath;
   std::string m_title;
   std::string m_author;
   uint16_t m_defaultWidth;
   uint16_t m_defaultHeight;
-  uint8_t m_bitDepth;  // 1 = XTC/XTG (1-bit), 2 = XTCH/XTH (2-bit)
+  uint8_t m_bitDepth;
   bool m_hasChapters;
+  bool m_chaptersLoaded = false;
   XtcError m_lastError;
+  uint32_t m_accessCounter = 0;
+
+  // L1: Hot cache (fixed 4 entries)
+  std::array<L1CacheEntry, L1_CACHE_SIZE> m_l1Cache;
+
+  // L2: Sliding window (fixed size array)
+  std::array<PageInfo, L2_WINDOW_SIZE> m_l2Window;
+  uint32_t m_l2WindowStart = 0;
+  size_t m_l2WindowCount = 0;
+  bool m_l2Valid = false;
+
+  // Chapters (usually few, keep in memory)
+  std::vector<ChapterInfo> m_chapters;
+
+  // Original Page Table offset (for rebuilding cache)
+  uint64_t m_pageTableOffset = 0;
 
   // Internal helper functions
   XtcError readHeader();
-  XtcError readPageTable();
   XtcError readTitle();
   XtcError readAuthor();
   XtcError readChapters();
+  void ensureChaptersLoaded();
+
+  // L3 cache management
+  bool isPageTableCacheValid() const;
+  XtcError buildPageTableCache();
+  bool openCacheFile();
+  void closeCacheFile();
+
+  // L1/L2 cache operations
+  bool lookupL1(uint32_t pageIndex, PageInfo& info);
+  void updateL1(uint32_t pageIndex, const PageInfo& info);
+  bool lookupL2(uint32_t pageIndex, PageInfo& info);
+  void loadL2Window(uint32_t centerPage);
+
+  // Safe deserialization (alignment-safe for ESP32-C3)
+  static void safeDeserializeHeader(const uint8_t* buf, PageTableCacheHeader& header);
+  static void safeSerializeHeader(uint8_t* buf, const PageTableCacheHeader& header);
+
+  // Utility functions
+  uint32_t calculateFileHash(const char* filepath) const;
 };
 
 }  // namespace xtc