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.
31const uint32 kBlockCurrentVersion = 0x30000;  // Version 3.0.
32
33const uint32 kBlockMagic = 0xC104CAC3;
34const int kBlockHeaderSize = 8192;  // Two pages: almost 64k entries
35const int kMaxBlocks = (kBlockHeaderSize - 80) * 8;
36
37// Bitmap to track used blocks on a block-file.
38typedef uint32 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:
48struct BlockFileHeader {
49  uint32          magic;
50  uint32          version;
51  int16           this_file;    // Index of this file.
52  int16           next_file;    // Next file when this one is full.
53  int32           entry_size;   // Size of the blocks of this file.
54  int32           num_entries;  // Number of stored entries.
55  int32           max_entries;  // Current maximum number of entries.
56  int32           empty[4];     // Counters of empty entries for each type.
57  int32           hints[4];     // Last used position for each entry type.
58  volatile int32  updating;     // Keep track of updates to the header.
59  int32           user[5];
60  AllocBitmap     allocation_map;
61};
62
63COMPILE_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.
104struct SparseHeader {
105  int64 signature;          // The parent and children signature.
106  uint32 magic;             // Structure identifier (equal to kIndexMagic).
107  int32 parent_key_len;     // Key length for the parent entry.
108  int32 last_block;         // Index of the last written block.
109  int32 last_block_len;     // Lenght of the last written block.
110  int32 dummy[10];
111};
112
113// The SparseHeader will be followed by a bitmap, as described by this
114// structure.
115struct SparseData {
116  SparseHeader header;
117  uint32 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.
125const int kNumSparseBits = 1024;
126COMPILE_ASSERT(sizeof(SparseData) == sizeof(SparseHeader) + kNumSparseBits / 8,
127               Invalid_SparseData_bitmap);
128
129}  // namespace disk_cache
130
131#endif  // NET_DISK_CACHE_DISK_FORMAT_BASE_H_
132