src/vppinfra/maplog.h

   1 /*
   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:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   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.
  14  */
  15
  16 #ifndef __included_maplog_h__
  17 #define __included_maplog_h__
  18
  19 /** @file
  20     @brief mmap-based thread-safe fixed-size record double-buffered logging.
  21
  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
  25    to a log entry.
  26
  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.
  30 */
  31
  32 #include <vppinfra/clib.h>
  33 #include <vppinfra/cache.h>
  34 #include <vppinfra/format.h>
  35 #include <string.h>
  36 #include <sys/types.h>
  37 #include <sys/stat.h>
  38 #include <fcntl.h>
  39 #include <sys/mman.h>
  40
  41 /** Maplog log file header segment. In a separate file */
  42
  43 typedef struct
  44 {
  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;
  61
  62 #define MAPLOG_MAJOR_VERSION 1
  63 #define MAPLOG_MINOR_VERSION 1
  64 #define MAPLOG_PATCH_VERSION 0
  65
  66 /** Process-private main data structure */
  67
  68 typedef struct
  69 {
  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  */
  78
  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 */
  82
  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 */
  89 } clib_maplog_main_t;
  90
  91 /* flag bits */
  92 #define CLIB_MAPLOG_FLAG_INIT   (1<<0)
  93 #define CLIB_MAPLOG_FLAG_CIRCULAR (1<<1)
  94 #define CLIB_MAPLOG_FLAG_WRAPPED (1<<2)
  95
  96 /** log initialization structure */
  97 typedef struct
  98 {
  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; /**< application major version number */
 105   u8 application_minor_version; /**< application minor version number */
 106   u8 application_patch_version; /**< application patch version number */
 107   u8 maplog_is_circular;        /**< single, circular log */
 108 } clib_maplog_init_args_t;
 109
 110 /* function prototypes */
 111
 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);
 116
 117 format_function_t format_maplog_header;
 118
 119 u8 *_clib_maplog_get_entry_slowpath (clib_maplog_main_t * mm,
 120                                      u64 my_record_index);
 121
 122 /**
 123  * @brief Obtain a log entry pointer
 124  *
 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
 128  *
 129  * @param[in] mm   maplog object pointer
 130  * @return    pointer to the allocated log entry
 131  */
 132 static inline void *
 133 clib_maplog_get_entry (clib_maplog_main_t * mm)
 134 {
 135   u64 my_record_index;
 136   u8 *rv;
 137
 138   ASSERT (mm->flags & CLIB_MAPLOG_FLAG_INIT);
 139
 140   my_record_index = __sync_fetch_and_add (&mm->next_record_index, 1);
 141
 142   /* Time to unmap and create a new logfile? */
 143   if (PREDICT_FALSE ((my_record_index & (mm->file_size_in_records - 1)) == 0))
 144     {
 145       /* Regular log? Switch file... */
 146       if (!(mm->flags & CLIB_MAPLOG_FLAG_CIRCULAR))
 147         {
 148           /* Yes, but not the very first time... (;-)... */
 149           if (my_record_index)
 150             return _clib_maplog_get_entry_slowpath (mm, my_record_index);
 151         }
 152       else                      /* Circular log: set the wrap bit and move along */
 153         mm->flags |= CLIB_MAPLOG_FLAG_WRAPPED;
 154       /* FALLTHROUGH */
 155     }
 156
 157   rv = (u8 *)
 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;
 161
 162   return rv;
 163 }
 164
 165 #endif /* __included_maplog_h__ */
 166
 167 /*
 168  * fd.io coding-style-patch-verification: ON
 169  *
 170  * Local Variables:
 171  * eval: (c-set-style "gnu")
 172  * End:
 173  */