usr.sbin/fifolog/lib/fifolog.h

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