sd_output.hpp

Go to the documentation of this file.

/*
 * sd_output.hpp — SD card log sink for SBL logger
 *
 * Per-boot sequential log files with size and count limits.
 * Buffers writes to a 512-byte sector-aligned buffer and flushes
 * to SD card via FatFs. Call flush() periodically from the main
 * loop (never from ISR).
 *
 * Usage:
 *   // Mount FatFs first, then:
 *   SdLogConfig cfg;
 *   cfg.millis = sbl::driver::Timer::millis;  // required
 *   SdLogOutput::init(cfg);
 *
 *   // In main loop:
 *   SdLogOutput::write("hello\r\n");
 *   SdLogOutput::flush();  // time-gated, safe to call every iteration
 */
 
#pragma once
 
#include "ff.h"
#include <cstring>
 
namespace sbl::log {
 
struct SdLogConfig {
    const char* prefix = "LOG";         // Filename prefix → LOG_000.TXT
    size_t max_file_bytes = 4*1024*1024;// 4MB per file (~24h of debug output)
    uint16_t max_files = 256;           // 256 files × 4MB = 1GB max card usage
    uint16_t flush_interval_ms = 100;   // Min ms between flushes (0 = every call)
    uint32_t (*millis)() = nullptr;     // Millisecond timestamp function (required)
};
 
class SdLogOutput {
public:
    /// Initialize: scan existing files, create next sequential log.
    /// Returns true if log file was opened successfully.
    static bool init(const SdLogConfig& cfg = {}) {
        s_cfg = cfg;
        s_pos = 0;
        s_file_bytes = 0;
        s_last_flush_ms = 0;
        s_open = false;
 
        // Find the next available file number
        s_current_num = find_next_file_number();
 
        // If we've hit max_files, delete the oldest to make room
        if (s_current_num >= s_cfg.max_files) {
            delete_oldest();
            s_current_num = find_next_file_number();
        }
 
        return open_file(s_current_num);
    }
 
    /// Logger sink interface — buffers data, auto-flushes when buffer is full.
    static void write(const char* str) {
        if (!s_open) return;
        size_t len = strlen(str);
        const char* p = str;
        while (len > 0) {
            size_t space = BUF_SIZE - s_pos;
            size_t chunk = len < space ? len : space;
            memcpy(s_buf + s_pos, p, chunk);
            s_pos += chunk;
            p += chunk;
            len -= chunk;
            if (s_pos >= BUF_SIZE) {
                flush_buffer();
            }
        }
    }
 
    /// Time-gated flush. Safe to call every main loop iteration.
    /// Only writes to SD if flush_interval_ms has elapsed or buffer is >75% full.
    static void flush() {
        if (!s_open || s_pos == 0) return;
 
        bool time_to_flush = true;
        if (s_cfg.millis && s_cfg.flush_interval_ms > 0) {
            uint32_t now = s_cfg.millis();
            uint32_t elapsed = now - s_last_flush_ms;
            time_to_flush = (elapsed >= s_cfg.flush_interval_ms) ||
                            (s_pos >= BUF_SIZE * 3 / 4);
        }
 
        if (time_to_flush) {
            flush_buffer();
        }
    }
 
    /// Flush immediately, bypassing time gate.
    static void force_flush() {
        if (!s_open || s_pos == 0) return;
        flush_buffer();
    }
 
    /// Close file (flushes first). Call before removing card.
    static void close() {
        if (!s_open) return;
        force_flush();
        f_close(&s_fil);
        s_open = false;
    }
 
    static bool is_open() { return s_open; }
 
private:
    static constexpr size_t BUF_SIZE = 512;
    static constexpr size_t NAME_BUF = 16;  // "LOG_000.TXT\0"
 
    static void make_filename(char* buf, uint16_t num) {
        // Build PREFIX_NNN.TXT (8.3 format)
        size_t i = 0;
        const char* p = s_cfg.prefix;
        while (*p && i < 4) buf[i++] = *p++;
        buf[i++] = '_';
        buf[i++] = '0' + (num / 100) % 10;
        buf[i++] = '0' + (num / 10) % 10;
        buf[i++] = '0' + num % 10;
        buf[i++] = '.';
        buf[i++] = 'T';
        buf[i++] = 'X';
        buf[i++] = 'T';
        buf[i] = '\0';
    }
 
    static uint16_t find_next_file_number() {
        // Find the lowest unused file number
        char name[NAME_BUF];
        FILINFO fno;
        for (uint16_t n = 0; n < s_cfg.max_files; n++) {
            make_filename(name, n);
            if (f_stat(name, &fno) != FR_OK) {
                return n;  // File doesn't exist — use this number
            }
        }
        return s_cfg.max_files;  // All slots full
    }
 
    static void delete_oldest() {
        // Delete file 0 and shift all others down
        // Simple approach: just delete the lowest-numbered file
        char name[NAME_BUF];
        FILINFO fno;
        for (uint16_t n = 0; n < s_cfg.max_files; n++) {
            make_filename(name, n);
            if (f_stat(name, &fno) == FR_OK) {
                f_unlink(name);
                return;  // Deleted oldest, now find_next will find the gap
            }
        }
    }
 
    static bool open_file(uint16_t num) {
        char name[NAME_BUF];
        make_filename(name, num);
        FRESULT fr = f_open(&s_fil, name, FA_WRITE | FA_CREATE_NEW);
        if (fr != FR_OK) return false;
        s_open = true;
        s_file_bytes = 0;
        return true;
    }
 
    static bool rotate_file() {
        // Close current, open next
        f_close(&s_fil);
        s_open = false;
        s_current_num++;
 
        if (s_current_num >= s_cfg.max_files) {
            delete_oldest();
            s_current_num = find_next_file_number();
        }
 
        return open_file(s_current_num);
    }
 
    static void flush_buffer() {
        if (s_pos == 0) return;
 
        // Check if we need to rotate before writing
        if (s_cfg.max_file_bytes > 0 &&
            s_file_bytes + s_pos > s_cfg.max_file_bytes) {
            if (!rotate_file()) {
                s_pos = 0;
                return;  // Rotation failed, drop data
            }
        }
 
        UINT bw;
        f_write(&s_fil, s_buf, s_pos, &bw);
        f_sync(&s_fil);
        s_file_bytes += bw;
        s_pos = 0;
 
        if (s_cfg.millis) {
            s_last_flush_ms = s_cfg.millis();
        }
    }
 
    static inline SdLogConfig s_cfg;
    static inline FIL s_fil;
    static inline char s_buf[BUF_SIZE];
    static inline size_t s_pos = 0;
    static inline size_t s_file_bytes = 0;
    static inline uint16_t s_current_num = 0;
    static inline uint32_t s_last_flush_ms = 0;
    static inline bool s_open = false;
};
 
} // namespace sbl::log