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