net/disk_cache/blockfile/disk_format_base.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // For a general description of the files used by the cache see file_format.h.
   6 //
   7 // A block file is a file designed to store blocks of data of a given size. It
   8 // is able to store data that spans from one to four consecutive "blocks", and
   9 // it grows as needed to store up to approximately 65000 blocks. It has a fixed
  10 // size header used for book keeping such as tracking free of blocks on the
  11 // file. For example, a block-file for 1KB blocks will grow from 8KB when
  12 // totally empty to about 64MB when completely full. At that point, data blocks
  13 // of 1KB will be stored on a second block file that will store the next set of
  14 // 65000 blocks. The first file contains the number of the second file, and the
  15 // second file contains the number of a third file, created when the second file
  16 // reaches its limit. It is important to remember that no matter how long the
  17 // chain of files is, any given block can be located directly by its address,
  18 // which contains the file number and starting block inside the file.
  19
  20 #ifndef NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_BASE_H_
  21 #define NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_BASE_H_
  22
  23 #include "base/basictypes.h"
  24 #include "net/base/net_export.h"
  25
  26 namespace disk_cache {
  27
  28 typedef uint32 CacheAddr;
  29
  30 const uint32 kBlockVersion2 = 0x20000;  // Version 2.0.
  31 const uint32 kBlockCurrentVersion = 0x30000;  // Version 3.0.
  32
  33 const uint32 kBlockMagic = 0xC104CAC3;
  34 const int kBlockHeaderSize = 8192;  // Two pages: almost 64k entries
  35 const int kMaxBlocks = (kBlockHeaderSize - 80) * 8;
  36 const int kNumExtraBlocks = 1024;  // How fast files grow.
  37
  38 // Bitmap to track used blocks on a block-file.
  39 typedef uint32 AllocBitmap[kMaxBlocks / 32];
  40
  41 // A block-file is the file used to store information in blocks (could be
  42 // EntryStore blocks, RankingsNode blocks or user-data blocks).
  43 // We store entries that can expand for up to 4 consecutive blocks, and keep
  44 // counters of the number of blocks available for each type of entry. For
  45 // instance, an entry of 3 blocks is an entry of type 3. We also keep track of
  46 // where did we find the last entry of that type (to avoid searching the bitmap
  47 // from the beginning every time).
  48 // This Structure is the header of a block-file:
  49 struct BlockFileHeader {
  50   uint32          magic;
  51   uint32          version;
  52   int16           this_file;    // Index of this file.
  53   int16           next_file;    // Next file when this one is full.
  54   int32           entry_size;   // Size of the blocks of this file.
  55   int32           num_entries;  // Number of stored entries.
  56   int32           max_entries;  // Current maximum number of entries.
  57   int32           empty[4];     // Counters of empty entries for each type.
  58   int32           hints[4];     // Last used position for each entry type.
  59   volatile int32  updating;     // Keep track of updates to the header.
  60   int32           user[5];
  61   AllocBitmap     allocation_map;
  62 };
  63
  64 static_assert(sizeof(BlockFileHeader) == kBlockHeaderSize, "bad header");
  65
  66 // Sparse data support:
  67 // We keep a two level hierarchy to enable sparse data for an entry: the first
  68 // level consists of using separate "child" entries to store ranges of 1 MB,
  69 // and the second level stores blocks of 1 KB inside each child entry.
  70 //
  71 // Whenever we need to access a particular sparse offset, we first locate the
  72 // child entry that stores that offset, so we discard the 20 least significant
  73 // bits of the offset, and end up with the child id. For instance, the child id
  74 // to store the first megabyte is 0, and the child that should store offset
  75 // 0x410000 has an id of 4.
  76 //
  77 // The child entry is stored the same way as any other entry, so it also has a
  78 // name (key). The key includes a signature to be able to identify children
  79 // created for different generations of the same resource. In other words, given
  80 // that a given sparse entry can have a large number of child entries, and the
  81 // resource can be invalidated and replaced with a new version at any time, it
  82 // is important to be sure that a given child actually belongs to certain entry.
  83 //
  84 // The full name of a child entry is composed with a prefix ("Range_"), and two
  85 // hexadecimal 64-bit numbers at the end, separated by semicolons. The first
  86 // number is the signature of the parent key, and the second number is the child
  87 // id as described previously. The signature itself is also stored internally by
  88 // the child and the parent entries. For example, a sparse entry with a key of
  89 // "sparse entry name", and a signature of 0x052AF76, may have a child entry
  90 // named "Range_sparse entry name:052af76:4", which stores data in the range
  91 // 0x400000 to 0x4FFFFF.
  92 //
  93 // Each child entry keeps track of all the 1 KB blocks that have been written
  94 // to the entry, but being a regular entry, it will happily return zeros for any
  95 // read that spans data not written before. The actual sparse data is stored in
  96 // one of the data streams of the child entry (at index 1), while the control
  97 // information is stored in another stream (at index 2), both by parents and
  98 // the children.
  99
 100 // This structure contains the control information for parent and child entries.
 101 // It is stored at offset 0 of the data stream with index 2.
 102 // It is possible to write to a child entry in a way that causes the last block
 103 // to be only partialy filled. In that case, last_block and last_block_len will
 104 // keep track of that block.
 105 struct SparseHeader {
 106   int64 signature;          // The parent and children signature.
 107   uint32 magic;             // Structure identifier (equal to kIndexMagic).
 108   int32 parent_key_len;     // Key length for the parent entry.
 109   int32 last_block;         // Index of the last written block.
 110   int32 last_block_len;     // Lenght of the last written block.
 111   int32 dummy[10];
 112 };
 113
 114 // The SparseHeader will be followed by a bitmap, as described by this
 115 // structure.
 116 struct SparseData {
 117   SparseHeader header;
 118   uint32 bitmap[32];        // Bitmap representation of known children (if this
 119                             // is a parent entry), or used blocks (for child
 120                             // entries. The size is fixed for child entries but
 121                             // not for parents; it can be as small as 4 bytes
 122                             // and as large as 8 KB.
 123 };
 124
 125 // The number of blocks stored by a child entry.
 126 const int kNumSparseBits = 1024;
 127 static_assert(sizeof(SparseData) == sizeof(SparseHeader) + kNumSparseBits / 8,
 128               "invalid SparseData bitmap");
 129
 130 }  // namespace disk_cache
 131
 132 #endif  // NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_BASE_H_