sdLog.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013-2016 Gautier Hattenberger, Alexandre Bustico
 *
 * This file is part of paparazzi.
 *
 * paparazzi is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * paparazzi is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with paparazzi; see the file COPYING.  If not, write to
 * the Free Software Foundation, 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

/*
 * @file modules/loggers/sdlog_chibios/sdLog.h
 * @brief sdlog API using ChibiOS and Fatfs
 *
 */

#pragma once
#include "std.h"
#include "mcuconf.h"

#include <stdarg.h>

#define NUMBERLEN 4
#define NUMBERMAX 9999
#define NUMBERFMF "%s\\%s%.04d.LOG"

#ifdef __cplusplus
extern "C" {
#endif

/*
  This module is highly coupled with fatfs, and mcuconf.h
  several MACRO should be defined before use

  FATFS (ffconf.h)


 mcuconf.h (or any other header included before sdLog.h
 ° SDLOG_ALL_BUFFERS_SIZE : (in bytes) cache buffer size shared between all opened log file
          minumum size by  opened log file should be at least 512 and
          should be a POWER OF TWO
 ° SDLOG_MAX_MESSAGE_LEN  : (in bytes) maximum length of a message
 ° SDLOG_QUEUE_BUCKETS    : number of entries in bufering queue
 ° SDLOG_NUM_FILES     : number of simultaneous opened log files

 EXAMPLE:
 #define SDLOG_QUEUE_BUCKETS  1024
 #define SDLOG_MAX_MESSAGE_LEN 252
 #define SDLOG_NUM_FILES 1
 #define SDLOG_ALL_BUFFERS_SIZE (SDLOG_NUM_FILES*4096)



 use of the api :
 sdLogInit (initialize peripheral,  verify sdCard availibility)
 sdLogOpenLog : open file
 sdLogWriteXXX : write log using one off the many function of the API
 sdLogCloseLog : close log
 sdLogFinish : terminate logging thread


 and asynchronous emergency close (power outage detection by example) :
 sdLogCloseAllLogs
 sdLogFinish

 + ADVICE for maximizing throughtput by order of inportance
 ° define STM32_SDC_SDIO_UNALIGNED_SUPPORT to  FALSE in mcuconf.h
 ° do not use sdLogFlushXXX API but instead give a flush period of 10 in sdLogOpenLog
 ° SDLOG_ALL_BUFFERS_SIZE/SDLOG_NUM_FILES should be around 8192 and a power of two
 ° reserve contiguous room for your entire log file using sdLogExpandLogFile
   just after opening log
 ° use class 10 SD card

 +  ADVICE for maximizing reliability
 ° survey power loss, and call sdLogCloseAllLogs (false) when power loss is detected
   after having powered off all you can (LEDs or anything draining power from MCU pins)
 ° always check return status of function (sdLogOpenLog will fail if filesystem is dirty)
 ° always check filesystem health with fsck (linux) or CHKDSK (windows) when
   mounting sd card on a computer

 */


#if SDLOG_ALL_BUFFERS_SIZE == 0 || SDLOG_MAX_MESSAGE_LEN == 0 || \
    SDLOG_QUEUE_BUCKETS  == 0
#undef SDLOG_NEED_QUEUE
#else
#define SDLOG_NEED_QUEUE
#endif


#ifdef SDLOG_NEED_QUEUE
typedef struct LogMessage LogMessage;
#endif

typedef enum {
  SDLOG_OK,
  SDLOG_NOCARD,
  SDLOG_FATFS_ERROR,
  SDLOG_FATFS_NOENT,
  SDLOG_FSFULL,
  SDLOG_FDFULL,
  SDLOG_QUEUEFULL,
  SDLOG_MEMFULL,
  SDLOG_NOTHREAD,
  SDLOG_INTERNAL_ERROR,
  SDLOG_CANNOT_EXPAND,
  SDLOG_LOGNUM_ERROR,
  SDLOG_WAS_LAUNCHED,
} SdioError;

typedef struct _SdLogBuffer SdLogBuffer;
typedef int8_t FileDes;



SdioError sdLogInit(uint32_t *freeSpaceInKo);

SdioError getFileName(const char *prefix, const char *directoryName,
                      char *nextFileName, const size_t nameLength, const int indexOffset);




SdioError removeEmptyLogs(const char *directoryName, const char *prefix,
                          const size_t sizeConsideredEmpty);
SdioError sdLogFinish(void);


#ifdef SDLOG_NEED_QUEUE

SdioError sdLogOpenLog(FileDes *fileObject, const char *directoryName, const char *fileName,
                       const uint32_t autoFlushPeriod, const bool appendTagAtClose,
           const size_t sizeInMo, const bool preallocate);




SdioError sdLogFlushLog(const FileDes fileObject);


SdioError sdLogFlushAllLogs(void);

SdioError sdLogCloseLog(const FileDes fileObject);

SdioError sdLogCloseAllLogs(bool flush);


SdioError sdLogWriteLog(const FileDes fileObject, const char *fmt, ...)
  __attribute__ ((format (printf, 2, 3)));;


SdioError sdLogWriteRaw(const FileDes fileObject, const uint8_t *buffer, const size_t len);


SdioError sdLogAllocSDB(SdLogBuffer **sdb, const size_t len);

char      *sdLogGetBufferFromSDB(SdLogBuffer *sdb);


bool      sdLogSeekBufferFromSDB(SdLogBuffer *sdb, uint32_t offset);


size_t sdLogGetBufferLenFromSDB(SdLogBuffer *sdb);

SdioError sdLogWriteSDB(const FileDes fd, SdLogBuffer *sdb);


SdioError sdLogWriteByte(const FileDes fileObject, const uint8_t value);

size_t sdLogGetNbBytesWrittenToStorage(void);

SdioError sdLogGetStorageStatus(void);


#endif


#ifdef __cplusplus
}
#endif