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