Paparazzi UAS  v5.18.0_stable
Paparazzi is a free software Unmanned Aircraft System.
sdLog.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2013-2016 Gautier Hattenberger, Alexandre Bustico
3  *
4  * This file is part of paparazzi.
5  *
6  * paparazzi is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2, or (at your option)
9  * any later version.
10  *
11  * paparazzi is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with paparazzi; see the file COPYING. If not, write to
18  * the Free Software Foundation, 59 Temple Place - Suite 330,
19  * Boston, MA 02111-1307, USA.
20  */
21 
22 /*
23  * @file modules/loggers/sdlog_chibios/sdLog.h
24  * @brief sdlog API using ChibiOS and Fatfs
25  *
26  */
27 
28 #pragma once
29 #include "std.h"
30 #include "mcuconf.h"
31 
32 #include <stdarg.h>
33 
34 #define NUMBERLEN 4
35 #define NUMBERMAX 9999
36 #define NUMBERFMF "%s\\%s%.04d.LOG"
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 /*
43  This module is highly coupled with fatfs, and mcuconf.h
44  several MACRO should be defined before use
45 
46  FATFS (ffconf.h)
47 
48 
49  mcuconf.h (or any other header included before sdLog.h
50  ° SDLOG_ALL_BUFFERS_SIZE : (in bytes) cache buffer size shared between all opened log file
51  minumum size by opened log file should be at least 512 and
52  should be a POWER OF TWO
53  ° SDLOG_MAX_MESSAGE_LEN : (in bytes) maximum length of a message
54  ° SDLOG_QUEUE_BUCKETS : number of entries in bufering queue
55  ° SDLOG_NUM_FILES : number of simultaneous opened log files
56 
57  EXAMPLE:
58  #define SDLOG_QUEUE_BUCKETS 1024
59  #define SDLOG_MAX_MESSAGE_LEN 252
60  #define SDLOG_NUM_FILES 1
61  #define SDLOG_ALL_BUFFERS_SIZE (SDLOG_NUM_FILES*4096)
62 
63 
64 
65  use of the api :
66  sdLogInit (initialize peripheral, verify sdCard availibility)
67  sdLogOpenLog : open file
68  sdLogWriteXXX : write log using one off the many function of the API
69  sdLogCloseLog : close log
70  sdLogFinish : terminate logging thread
71 
72 
73  and asynchronous emergency close (power outage detection by example) :
74  sdLogCloseAllLogs
75  sdLogFinish
76 
77  + ADVICE for maximizing throughtput by order of inportance
78  ° define STM32_SDC_SDIO_UNALIGNED_SUPPORT to FALSE in mcuconf.h
79  ° do not use sdLogFlushXXX API but instead give a flush period of 10 in sdLogOpenLog
80  ° SDLOG_ALL_BUFFERS_SIZE/SDLOG_NUM_FILES should be around 8192 and a power of two
81  ° reserve contiguous room for your entire log file using sdLogExpandLogFile
82  just after opening log
83  ° use class 10 SD card
84 
85  + ADVICE for maximizing reliability
86  ° survey power loss, and call sdLogCloseAllLogs (false) when power loss is detected
87  after having powered off all you can (LEDs or anything draining power from MCU pins)
88  ° always check return status of function (sdLogOpenLog will fail if filesystem is dirty)
89  ° always check filesystem health with fsck (linux) or CHKDSK (windows) when
90  mounting sd card on a computer
91 
92  */
93 
94 
95 #if SDLOG_ALL_BUFFERS_SIZE == 0 || SDLOG_MAX_MESSAGE_LEN == 0 || \
96  SDLOG_QUEUE_BUCKETS == 0
97 #undef SDLOG_NEED_QUEUE
98 #else
99 #define SDLOG_NEED_QUEUE
100 #endif
101 
102 #define LOG_PREALLOCATION_ENABLED true
103 #define LOG_PREALLOCATION_DISABLED false
104 #define LOG_APPEND_TAG_AT_CLOSE_ENABLED true
105 #define LOG_APPEND_TAG_AT_CLOSE_DISABLED false
106 
107 #ifdef SDLOG_NEED_QUEUE
108 typedef struct LogMessage LogMessage;
109 #endif
110 
111 typedef enum {
125 } SdioError;
126 
127 typedef struct _SdLogBuffer SdLogBuffer;
128 typedef int8_t FileDes;
129 
130 
131 
141 SdioError sdLogInit(uint32_t *freeSpaceInKo);
142 
157 SdioError getFileName(const char *prefix, const char *directoryName,
158  char *nextFileName, const size_t nameLength, const int indexOffset);
159 
160 
161 
162 
174 SdioError removeEmptyLogs(const char *directoryName, const char *prefix,
175  const size_t sizeConsideredEmpty);
183 SdioError sdLogFinish(void);
184 
185 
186 #ifdef SDLOG_NEED_QUEUE
187 
207 SdioError sdLogOpenLog(FileDes *fileObject, const char *directoryName, const char *prefix,
208  const uint32_t autoFlushPeriod, const bool appendTagAtClose,
209  const size_t sizeInMo, const bool preallocate, char *fileName, const size_t nameLength);
210 
211 
212 
213 
221 SdioError sdLogFlushLog(const FileDes fileObject);
222 
223 
230 SdioError sdLogFlushAllLogs(void);
231 
237 SdioError sdLogCloseLog(const FileDes fileObject);
238 
247 SdioError sdLogCloseAllLogs(bool flush);
248 
249 
256 SdioError sdLogWriteLog(const FileDes fileObject, const char *fmt, ...)
257  __attribute__ ((format (printf, 2, 3)));;
258 
259 
267 SdioError sdLogWriteRaw(const FileDes fileObject, const uint8_t *buffer, const size_t len);
268 
269 
284 SdioError sdLogAllocSDB(SdLogBuffer **sdb, const size_t len);
285 
293 char *sdLogGetBufferFromSDB(SdLogBuffer *sdb);
294 
295 
305 bool sdLogSeekBufferFromSDB(SdLogBuffer *sdb, uint32_t offset);
306 
307 
315 size_t sdLogGetBufferLenFromSDB(SdLogBuffer *sdb);
316 
324 SdioError sdLogWriteSDB(const FileDes fd, SdLogBuffer *sdb);
325 
326 
333 SdioError sdLogWriteByte(const FileDes fileObject, const uint8_t value);
334 
340 size_t sdLogGetNbBytesWrittenToStorage(void);
341 
346 SdioError sdLogGetStorageStatus(void);
347 
348 
349 #endif
350 
351 
352 #ifdef __cplusplus
353 }
354 #endif
355 
356 
SDLOG_FSFULL
@ SDLOG_FSFULL
Definition: sdLog.h:116
SDLOG_OK
@ SDLOG_OK
Definition: sdLog.h:112
SDLOG_FATFS_ERROR
@ SDLOG_FATFS_ERROR
Definition: sdLog.h:114
SdLogBuffer
struct _SdLogBuffer SdLogBuffer
Definition: sdLog.h:127
SDLOG_FDFULL
@ SDLOG_FDFULL
Definition: sdLog.h:117
uint32_t
unsigned long uint32_t
Definition: types.h:18
SDLOG_INTERNAL_ERROR
@ SDLOG_INTERNAL_ERROR
Definition: sdLog.h:121
sdLogFinish
SdioError sdLogFinish(void)
unmount filesystem
Definition: sdLog.c:262
SDLOG_FATFS_NOENT
@ SDLOG_FATFS_NOENT
Definition: sdLog.h:115
SDLOG_MEMFULL
@ SDLOG_MEMFULL
Definition: sdLog.h:119
std.h
removeEmptyLogs
SdioError removeEmptyLogs(const char *directoryName, const char *prefix, const size_t sizeConsideredEmpty)
remove spurious log file left on sd
Definition: sdLog.c:791
SDLOG_QUEUEFULL
@ SDLOG_QUEUEFULL
Definition: sdLog.h:118
SDLOG_NOTHREAD
@ SDLOG_NOTHREAD
Definition: sdLog.h:120
uint8_t
unsigned char uint8_t
Definition: types.h:14
sdLogInit
SdioError sdLogInit(uint32_t *freeSpaceInKo)
initialise sdLog
Definition: sdLog.c:202
getFileName
SdioError getFileName(const char *prefix, const char *directoryName, char *nextFileName, const size_t nameLength, const int indexOffset)
get last used name for a pattern, then add offset and return valid filename
Definition: sdLog.c:730
SDLOG_CANNOT_EXPAND
@ SDLOG_CANNOT_EXPAND
Definition: sdLog.h:122
FileDes
int8_t FileDes
Definition: sdLog.h:128
SDLOG_NOCARD
@ SDLOG_NOCARD
Definition: sdLog.h:113
fd
int fd
Definition: serial.c:26
offset
static const float offset[]
Definition: dw1000_arduino.c:199
int8_t
signed char int8_t
Definition: types.h:15
SDLOG_WAS_LAUNCHED
@ SDLOG_WAS_LAUNCHED
Definition: sdLog.h:124
SdioError
SdioError
Definition: sdLog.h:111
SDLOG_LOGNUM_ERROR
@ SDLOG_LOGNUM_ERROR
Definition: sdLog.h:123