usr.sbin/fifolog/lib/fifolog.h

   1 /*-
   2  * Copyright (c) 2005-2008 Poul-Henning Kamp
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  *
  26  * $FreeBSD$
  27  */
  28
  29 #ifndef __LOCAL_FIFOLOG_H_
  30 #define __LOCAL_FIFOLOG_H_
  31
  32 /*
  33  * Definitions for fifolog "protocol": the on-media layout.
  34  *
  35  * The fifolog on-media record has three layers:
  36  *   The outer timestamping and synchronization layer.
  37  *   The zlib implemented data compression.
  38  *   The inner sequencing and identification layer.
  39  *
  40  * All three layers are synchronized at a subset of the outer layer
  41  * record boundaries, from where reading can be initiated.
  42  *
  43  *
  44  * The outer layer:
  45  * -----------------
  46  * The first record in a fifolog contains a magic string and version
  47  * information along with a 32be encoded recordsize for all records
  48  * in the fifolog, including the first.
  49  * The recordsize is explicit to avoid ambiguities when a media is
  50  * moved from one machine to another.
  51  *
  52  * Each record in the fifolog has the following contents:
  53  *      offset  type    contents
  54  *      --------------------------------------------------------------
  55  *      0       32be    sequence_number
  56  *                      The sequence number is randomly chosen for the
  57  *                      fifolog and increments once for each record written.
  58  *                      It's presence allow quick identification of the next
  59  *                      record to be written using a binary search for the
  60  *                      first place where a discontinuity in the sequence
  61  *                      numbers occur.
  62  *      4        8      flags (FIFOLOG_FLG_*)
  63  *
  64  * If (flags & (FIFOLOG_FLG_SYNC)) the record is a synchronization point
  65  * at which the inner layers are aligned so that reading can be started
  66  * at this point.
  67  * To enable seeks into the file based on timestamps, a third field is
  68  * present in these records as well:
  69  *      5       32be    time_t containing POSIX's understanding of UTC.
  70  *
  71  * These fields are immediately followed by the inner layer payload as
  72  * described below, which has variable length.
  73  *
  74  * If the inner layer payload is shorter than the available space in
  75  * the record, it is padded with zero bytes, and the number of unused
  76  * bytes, including the encoded length thereof is recorded at the end
  77  * of the record as follows:
  78  *
  79  * If (flags & FIFOLOG_FLG_1BYTE)
  80  *      n-1     8       number of unused bytes
  81  * else if (flags & FIFOLOG_FLG_4BYTE)
  82  *      n-4     32be    number of unused bytes
  83  *
  84  *
  85  * The gzip layer
  86  * --------------
  87  * Is just output from zlib, nothing special here.  FIFOLOG_FLG_SYNC
  88  * corresponds to Z_FINISH flags to zlib.
  89  * In most cases, the timer will expire before zlib has filled an entire
  90  * record in which case Z_SYNC_FLUSH will be used to force as much as
  91  * possible into the buffer before it is written.  This is not marked
  92  * in outer layer (apart from a natural correlation with padding) since
  93  * zlibs data stream handles this without help.
  94  *
  95  *
  96  * The inner layer:
  97  * ----------------
  98  * The inner layer contains data identification and to the second
  99  * timestamping (the timestamp in the outer layer only marks the
 100  * first possible timestamp for content in the SYNC record).
 101  *
 102  *      offset  type    contents
 103  *      --------------------------------------------------------------
 104  *      0       32be    ident
 105  *
 106  * The bottom 30 bits of the identification word are application defined,
 107  * presently unused in the stand-alone fifolog tools, but used in the
 108  * original "measured" application that originated the fifolog format.
 109  * Should for instance syslogd(8) grow native support for fifolog format,
 110  * it could store the message priority here.
 111  *
 112  * If (ident & FIFOLOG_TIMESTAMP) the record is prefixed by:
 113  *      4       32be    time_t containing POSIX's understanding of UTC.
 114  *
 115  * Then follows the content, either as a NUL terminated string or as
 116  * a length encoded binary sequence:
 117  *
 118  * If (ident & FIFOLOG_LENGTH) the record is prefixed by:
 119  *      {0|4}   8       length of binary data
 120  *
 121  */
 122
 123 /* Magic identification string */
 124 #define FIFOLOG_FMT_MAGIC       "Measured FIFOLOG Ver 1.01\n"
 125
 126 /* Offset of the 32be encoded recordsize in the first sector */
 127 #define FIFOLOG_OFF_BS          0x20
 128
 129 #define FIFOLOG_FLG_1BYTE       0x01
 130 #define FIFOLOG_FLG_4BYTE       0x02
 131 #define FIFOLOG_FLG_RESTART     0x40
 132 #define FIFOLOG_FLG_SYNC        0x80
 133
 134 #define FIFOLOG_TIMESTAMP       0x80000000
 135 #define FIFOLOG_LENGTH          0x40000000
 136 #define FIFOLOG_IDENT           0x3fffffff
 137
 138 #endif /* __LOCAL_FIFOLOG_H_ */