Paparazzi UAS  v5.15_devel-132-gbbc6108
Paparazzi is a free software Unmanned Aircraft System.
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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 
205 SdioError sdLogOpenLog(FileDes *fileObject, const char *directoryName, const char *fileName,
206  const uint32_t autoFlushPeriod, const bool appendTagAtClose,
207  const size_t sizeInMo, const bool preallocate);
208 
209 
210 
211 
219 SdioError sdLogFlushLog(const FileDes fileObject);
220 
221 
228 SdioError sdLogFlushAllLogs(void);
229 
235 SdioError sdLogCloseLog(const FileDes fileObject);
236 
245 SdioError sdLogCloseAllLogs(bool flush);
246 
247 
254 SdioError sdLogWriteLog(const FileDes fileObject, const char *fmt, ...)
255  __attribute__ ((format (printf, 2, 3)));;
256 
257 
265 SdioError sdLogWriteRaw(const FileDes fileObject, const uint8_t *buffer, const size_t len);
266 
267 
282 SdioError sdLogAllocSDB(SdLogBuffer **sdb, const size_t len);
283 
291 char *sdLogGetBufferFromSDB(SdLogBuffer *sdb);
292 
293 
303 bool sdLogSeekBufferFromSDB(SdLogBuffer *sdb, uint32_t offset);
304 
305 
313 size_t sdLogGetBufferLenFromSDB(SdLogBuffer *sdb);
314 
322 SdioError sdLogWriteSDB(const FileDes fd, SdLogBuffer *sdb);
323 
324 
331 SdioError sdLogWriteByte(const FileDes fileObject, const uint8_t value);
332 
338 size_t sdLogGetNbBytesWrittenToStorage(void);
339 
344 SdioError sdLogGetStorageStatus(void);
345 
346 
347 #endif
348 
349 
350 #ifdef __cplusplus
351 }
352 #endif
353 
354 
SdioError sdLogFinish(void)
unmount filesystem
Definition: sdLog.c:262
int8_t FileDes
Definition: sdLog.h:128
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:731
static const float offset[]
SdioError removeEmptyLogs(const char *directoryName, const char *prefix, const size_t sizeConsideredEmpty)
remove spurious log file left on sd
Definition: sdLog.c:792
unsigned long uint32_t
Definition: types.h:18
SdioError
Definition: sdLog.h:111
unsigned char uint8_t
Definition: types.h:14
int fd
Definition: serial.c:26
signed char int8_t
Definition: types.h:15
struct _SdLogBuffer SdLogBuffer
Definition: sdLog.h:127
SdioError sdLogInit(uint32_t *freeSpaceInKo)
initialise sdLog
Definition: sdLog.c:202