2 * Copyright (c) 2017 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 #ifndef __included_maplog_h__
17 #define __included_maplog_h__
20 @brief mmap-based thread-safe fixed-size record double-buffered logging.
22 This scheme should be about as fast as practicable. By fiat, log
23 records are rounded to a multiple of CLIB_CACHE_LINE_BYTES.
24 Consumer code calls clib_maplog_get_entry(...) to obtain a pointer
27 We use an atomic ticket-counter to dole out log entries. Whichever
28 client thread crosses the double-buffer boundary is in charge of
29 replacing the log segment which just filled.
32 #include <vppinfra/clib.h>
33 #include <vppinfra/cache.h>
34 #include <vppinfra/format.h>
36 #include <sys/types.h>
41 /** Maplog log file header segment. In a separate file */
45 u8 maplog_major_version; /**< library major version number */
46 u8 maplog_minor_version; /**< library minor version number */
47 u8 maplog_patch_version; /**< library patch version number */
48 u8 maplog_flag_wrapped; /**< log has wrapped */
49 u32 application_id; /**< application identifier */
50 u8 application_major_version; /**< application major version number */
51 u8 application_minor_version; /**< application minor version number */
52 u8 application_patch_version; /**< application patch version number */
53 u8 maplog_flag_circular; /**< log is circular */
54 u32 record_size_in_cachelines; /**< record size in cache lines */
55 u32 cacheline_size; /**< cache line size */
56 u64 file_size_in_records; /**< file size in records */
57 u64 number_of_records; /**< number of records in entire log */
58 u64 number_of_files; /**< number of files in entire log */
59 u8 file_basename[256]; /**< file basename */
60 } clib_maplog_header_t;
62 #define MAPLOG_MAJOR_VERSION 1
63 #define MAPLOG_MINOR_VERSION 1
64 #define MAPLOG_PATCH_VERSION 0
66 /** Process-private main data structure */
70 CLIB_CACHE_LINE_ALIGN_MARK (cacheline1);
71 /** rw cache line: atomic ticket-counter, file index */
72 volatile u64 next_record_index;
73 /** file size in records, rounded to a power of two */
74 u64 file_size_in_records;
75 u32 log2_file_size_in_records; /**< lg file size in records */
76 volatile u32 current_file_index; /**< current file index */
77 volatile u32 flags; /**< flags, currently just "init" or not */
79 /* read-mostly cache line: size parameters, file names, etc. */
80 CLIB_CACHE_LINE_ALIGN_MARK (cacheline2);
81 u32 record_size_in_cachelines; /**< record size in cache lines */
83 /* double-buffered mmap'ed logfiles */
84 volatile u8 *file_baseva[2]; /**< active segment base addresses */
85 u8 *filenames[2]; /**< active segment file names */
86 /* vector not c-string */
87 u8 *file_basename; /**< basename, e.g. "/tmp/mylog" */
88 u8 *header_filename; /**< log header file name */
92 #define CLIB_MAPLOG_FLAG_INIT (1<<0)
93 #define CLIB_MAPLOG_FLAG_CIRCULAR (1<<1)
94 #define CLIB_MAPLOG_FLAG_WRAPPED (1<<2)
96 /** log initialization structure */
99 clib_maplog_main_t *mm; /**< pointer to the main structure */
100 char *file_basename; /**< file base name */
101 u64 file_size_in_bytes; /**< file size in bytes */
102 u32 record_size_in_bytes; /**< record size in bytes */
103 u32 application_id; /**< application identifier */
104 u8 application_major_version; /**< applcation major version number */
105 u8 application_minor_version; /**< applcation minor version number */
106 u8 application_patch_version; /**< applcation patch version number */
107 u8 maplog_is_circular; /**< single, circular log */
108 } clib_maplog_init_args_t;
110 /* function prototypes */
112 int clib_maplog_init (clib_maplog_init_args_t * ap);
113 void clib_maplog_update_header (clib_maplog_main_t * mm);
114 void clib_maplog_close (clib_maplog_main_t * mm);
115 int clib_maplog_process (char *file_basename, void *fp_arg);
117 format_function_t format_maplog_header;
119 u8 *_clib_maplog_get_entry_slowpath (clib_maplog_main_t * mm,
120 u64 my_record_index);
123 * @brief Obtain a log entry pointer
125 * Increments the atomic ticket counter, and returns a pointer to
126 * the newly-allocated log entry. The slowpath function replaces
127 * a full log segment with a new/fresh/empty log segment
129 * @param[in] mm maplog object pointer
130 * @return pointer to the allocated log entry
133 clib_maplog_get_entry (clib_maplog_main_t * mm)
138 ASSERT (mm->flags & CLIB_MAPLOG_FLAG_INIT);
140 my_record_index = __sync_fetch_and_add (&mm->next_record_index, 1);
142 /* Time to unmap and create a new logfile? */
143 if (PREDICT_FALSE ((my_record_index & (mm->file_size_in_records - 1)) == 0))
145 /* Regular log? Switch file... */
146 if (!(mm->flags & CLIB_MAPLOG_FLAG_CIRCULAR))
148 /* Yes, but not the very first time... (;-)... */
150 return _clib_maplog_get_entry_slowpath (mm, my_record_index);
152 else /* Circular log: set the wrap bit and move along */
153 mm->flags |= CLIB_MAPLOG_FLAG_WRAPPED;
158 mm->file_baseva[(my_record_index >> mm->log2_file_size_in_records) & 1] +
159 (my_record_index & (mm->file_size_in_records - 1))
160 * mm->record_size_in_cachelines * CLIB_CACHE_LINE_BYTES;
165 #endif /* __included_maplog_h__ */
168 * fd.io coding-style-patch-verification: ON
171 * eval: (c-set-style "gnu")