Paparazzi UAS  v5.14.0_stable-0-g3f680d1
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 
103 #ifdef SDLOG_NEED_QUEUE
104 typedef struct LogMessage LogMessage;
105 #endif
106 
107 typedef enum {
121 } SdioError;
122 
123 typedef struct _SdLogBuffer SdLogBuffer;
124 typedef int8_t FileDes;
125 
126 
127 
137 SdioError sdLogInit(uint32_t *freeSpaceInKo);
138 
153 SdioError getFileName(const char *prefix, const char *directoryName,
154  char *nextFileName, const size_t nameLength, const int indexOffset);
155 
156 
157 
158 
170 SdioError removeEmptyLogs(const char *directoryName, const char *prefix,
171  const size_t sizeConsideredEmpty);
179 SdioError sdLogFinish(void);
180 
181 
182 #ifdef SDLOG_NEED_QUEUE
183 
201 SdioError sdLogOpenLog(FileDes *fileObject, const char *directoryName, const char *fileName,
202  const uint32_t autoFlushPeriod, const bool appendTagAtClose,
203  const size_t sizeInMo, const bool preallocate);
204 
205 
206 
207 
215 SdioError sdLogFlushLog(const FileDes fileObject);
216 
217 
224 SdioError sdLogFlushAllLogs(void);
225 
231 SdioError sdLogCloseLog(const FileDes fileObject);
232 
241 SdioError sdLogCloseAllLogs(bool flush);
242 
243 
250 SdioError sdLogWriteLog(const FileDes fileObject, const char *fmt, ...)
251  __attribute__ ((format (printf, 2, 3)));;
252 
253 
261 SdioError sdLogWriteRaw(const FileDes fileObject, const uint8_t *buffer, const size_t len);
262 
263 
278 SdioError sdLogAllocSDB(SdLogBuffer **sdb, const size_t len);
279 
287 char *sdLogGetBufferFromSDB(SdLogBuffer *sdb);
288 
289 
299 bool sdLogSeekBufferFromSDB(SdLogBuffer *sdb, uint32_t offset);
300 
301 
309 size_t sdLogGetBufferLenFromSDB(SdLogBuffer *sdb);
310 
318 SdioError sdLogWriteSDB(const FileDes fd, SdLogBuffer *sdb);
319 
320 
327 SdioError sdLogWriteByte(const FileDes fileObject, const uint8_t value);
328 
334 size_t sdLogGetNbBytesWrittenToStorage(void);
335 
340 SdioError sdLogGetStorageStatus(void);
341 
342 
343 #endif
344 
345 
346 #ifdef __cplusplus
347 }
348 #endif
349 
350 
SdioError sdLogFinish(void)
unmount filesystem
Definition: sdLog.c:262
int8_t FileDes
Definition: sdLog.h:124
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:107
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:123
SdioError sdLogInit(uint32_t *freeSpaceInKo)
initialise sdLog
Definition: sdLog.c:202