summaryrefslogtreecommitdiffstats
path: root/src/vppinfra/maplog.h
diff options
context:
space:
mode:
authorDave Barach <dave@barachs.net>2017-12-01 16:20:32 -0500
committerDamjan Marion <dmarion.lists@gmail.com>2017-12-02 18:44:07 +0000
commit04fee31f265b1d8b602bf336ef1df6c917cf18b2 (patch)
tree0923dbecc069f4287db84d3946669010f974eec5 /src/vppinfra/maplog.h
parente2e9ce5cec3bacaa9445761d86ead2d582b46dca (diff)
maplog headers, offline processing, doxygen tags
Change-Id: I0545018ec02f3706ad6a2da6fc13537db5c31a2d Signed-off-by: Dave Barach <dave@barachs.net>
Diffstat (limited to 'src/vppinfra/maplog.h')
-rw-r--r--src/vppinfra/maplog.h94
1 files changed, 79 insertions, 15 deletions
diff --git a/src/vppinfra/maplog.h b/src/vppinfra/maplog.h
index 192dc22a71b..d1c23d20d29 100644
--- a/src/vppinfra/maplog.h
+++ b/src/vppinfra/maplog.h
@@ -16,9 +16,17 @@
#ifndef __included_maplog_h__
#define __included_maplog_h__
-/** \file
+/** @file
+ @brief mmap-based thread-safe fixed-size record double-buffered logging.
- mmap-based fixed-size record double-buffered logging
+ This scheme should be about as fast as practicable. By fiat, log
+ records are rounded to a multiple of CLIB_CACHE_LINE_BYTES.
+ Consumer code calls clib_maplog_get_entry(...) to obtain a pointer
+ to a log entry.
+
+ We use an atomic ticket-counter to dole out log entries. Whichever
+ client thread crosses the double-buffer boundary is in charge of
+ replacing the log segment which just filled.
*/
#include <vppinfra/clib.h>
@@ -30,37 +38,93 @@
#include <fcntl.h>
#include <sys/mman.h>
+/** Maplog log file header segment. In a separate file */
+
+typedef struct
+{
+ u8 maplog_major_version; /**< library major version number */
+ u8 maplog_minor_version; /**< library minor version number */
+ u8 maplog_patch_version; /**< library patch version number */
+ u8 pad;
+ u32 application_id; /**< application identifier */
+ u8 application_major_version; /**< application major version number */
+ u8 application_minor_version; /**< application minor version number */
+ u8 application_patch_version; /**< application patch version number */
+ u8 pad2;
+ u32 record_size_in_cachelines; /**< record size in cache lines */
+ u32 cacheline_size; /**< cache line size */
+ u64 file_size_in_records; /**< file size in records */
+ u64 number_of_records; /**< number of records in entire log */
+ u64 number_of_files; /**< number of files in entire log */
+ u8 file_basename[256]; /**< file basename */
+} clib_maplog_header_t;
+
+#define MAPLOG_MAJOR_VERSION 1
+#define MAPLOG_MINOR_VERSION 0
+#define MAPLOG_PATCH_VERSION 0
+
+/** Process-private main data structure */
+
typedef struct
{
- /* rw: atomic ticket-counter, file index */
CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
+ /** rw cache line: atomic ticket-counter, file index */
volatile u64 next_record_index;
- u64 file_size_in_records; /**< power of two */
- u32 log2_file_size_in_records;
- volatile u32 current_file_index;
- volatile u32 flags;
+ /** file size in records, rounded to a power of two */
+ u64 file_size_in_records;
+ u32 log2_file_size_in_records; /**< lg file size in records */
+ volatile u32 current_file_index; /**< current file index */
+ volatile u32 flags; /**< flags, currently just "init" or not */
- /* ro: size parameters */
+ /* read-mostly cache line: size parameters, file names, etc. */
CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
- u32 record_size_in_cachelines;
+ u32 record_size_in_cachelines; /**< record size in cache lines */
/* double-buffered mmap'ed logfiles */
- volatile u8 *file_baseva[2];
- u8 *filenames[2];
+ volatile u8 *file_baseva[2]; /**< active segment base addresses */
+ u8 *filenames[2]; /**< active segment file names */
/* vector not c-string */
- u8 *file_basename;
+ u8 *file_basename; /**< basename, e.g. "/tmp/mylog" */
+ u8 *header_filename; /**< log header file name */
} clib_maplog_main_t;
-int clib_maplog_init (clib_maplog_main_t * mm, char *file_basename,
- u64 file_size, u32 record_size_in_bytes);
+/* flag bits */
+#define CLIB_MAPLOG_FLAG_INIT (1<<0)
+/** log initialization structure */
+typedef struct
+{
+ clib_maplog_main_t *mm; /**< pointer to the main structure */
+ char *file_basename; /**< file base name */
+ u64 file_size_in_bytes; /**< file size in bytes */
+ u32 record_size_in_bytes; /**< record size in bytes */
+ u32 application_id; /**< application identifier */
+ u8 application_major_version; /**< applcation major version number */
+ u8 application_minor_version; /**< applcation minor version number */
+ u8 application_patch_version; /**< applcation patch version number */
+} clib_maplog_init_args_t;
+
+/* function prototypes */
+
+int clib_maplog_init (clib_maplog_init_args_t * ap);
void clib_maplog_close (clib_maplog_main_t * mm);
+int clib_maplog_process (char *file_basename, void *fp_arg);
-#define CLIB_MAPLOG_FLAG_INIT (1<<0)
+format_function_t format_maplog_header;
u8 *_clib_maplog_get_entry_slowpath (clib_maplog_main_t * mm,
u64 my_record_index);
+/**
+ * @brief Obtain a log entry pointer
+ *
+ * Increments the atomic ticket counter, and returns a pointer to
+ * the newly-allocated log entry. The slowpath function replaces
+ * a full log segment with a new/fresh/empty log segment
+ *
+ * @param[in] mm maplog object pointer
+ * @return pointer to the allocated log entry
+ */
static inline void *
clib_maplog_get_entry (clib_maplog_main_t * mm)
{