1 // Copyright (C) 2019 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #include <stdint.h> 18 #include <string> 19 20 namespace android { 21 namespace snapshot { 22 23 static constexpr uint64_t kCowMagicNumber = 0x436f77634f572121ULL; 24 static constexpr uint32_t kCowVersionMajor = 2; 25 static constexpr uint32_t kCowVersionMinor = 0; 26 27 static constexpr uint32_t kCowVersionManifest = 2; 28 29 static constexpr size_t BLOCK_SZ = 4096; 30 static constexpr size_t BLOCK_SHIFT = (__builtin_ffs(BLOCK_SZ) - 1); 31 32 // This header appears as the first sequence of bytes in the COW. All fields 33 // in the layout are little-endian encoded. The on-disk layout is: 34 // 35 // +-----------------------+ 36 // | Header (fixed) | 37 // +-----------------------+ 38 // | Scratch space | 39 // +-----------------------+ 40 // | Operation (variable) | 41 // | Data (variable) | 42 // +-----------------------+ 43 // | Footer (fixed) | 44 // +-----------------------+ 45 // 46 // The operations begin immediately after the header, and the "raw data" 47 // immediately follows the operation which refers to it. While streaming 48 // an OTA, we can immediately write the op and data, syncing after each pair, 49 // while storing operation metadata in memory. At the end, we compute data and 50 // hashes for the footer, which is placed at the tail end of the file. 51 // 52 // A missing or corrupt footer likely indicates that writing was cut off 53 // between writing the last operation/data pair, or the footer itself. In this 54 // case, the safest way to proceed is to assume the last operation is faulty. 55 56 struct CowHeader { 57 uint64_t magic; 58 uint16_t major_version; 59 uint16_t minor_version; 60 61 // Size of this struct. 62 uint16_t header_size; 63 64 // Size of footer struct 65 uint16_t footer_size; 66 67 // Size of op struct 68 uint16_t op_size; 69 70 // The size of block operations, in bytes. 71 uint32_t block_size; 72 73 // The number of ops to cluster together. 0 For no clustering. Cannot be 1. 74 uint32_t cluster_ops; 75 76 // Tracks merge operations completed 77 uint64_t num_merge_ops; 78 79 // Scratch space used during merge 80 uint32_t buffer_size; 81 } __attribute__((packed)); 82 83 // This structure is the same size of a normal Operation, but is repurposed for the footer. 84 struct CowFooterOperation { 85 // The operation code (always kCowFooterOp). 86 uint8_t type; 87 88 // If this operation reads from the data section of the COW, this contains 89 // the compression type of that data (see constants below). 90 uint8_t compression; 91 92 // Length of Footer Data. Currently 64 for both checksums 93 uint16_t data_length; 94 95 // The amount of file space used by Cow operations 96 uint64_t ops_size; 97 98 // The number of cow operations in the file 99 uint64_t num_ops; 100 } __attribute__((packed)); 101 102 struct CowFooterData { 103 // SHA256 checksums of Footer op 104 uint8_t footer_checksum[32]; 105 106 // SHA256 of the operation sequence. 107 uint8_t ops_checksum[32]; 108 } __attribute__((packed)); 109 110 // Cow operations are currently fixed-size entries, but this may change if 111 // needed. 112 struct CowOperation { 113 // The operation code (see the constants and structures below). 114 uint8_t type; 115 116 // If this operation reads from the data section of the COW, this contains 117 // the compression type of that data (see constants below). 118 uint8_t compression; 119 120 // If this operation reads from the data section of the COW, this contains 121 // the length. 122 uint16_t data_length; 123 124 // The block of data in the new image that this operation modifies. 125 uint64_t new_block; 126 127 // The value of |source| depends on the operation code. 128 // 129 // For copy operations, this is a block location in the source image. 130 // 131 // For replace operations, this is a byte offset within the COW's data 132 // sections (eg, not landing within the header or metadata). It is an 133 // absolute position within the image. 134 // 135 // For zero operations (replace with all zeroes), this is unused and must 136 // be zero. 137 // 138 // For Label operations, this is the value of the applied label. 139 // 140 // For Cluster operations, this is the length of the following data region 141 // 142 // For Xor operations, this is the byte location in the source image. 143 uint64_t source; 144 } __attribute__((packed)); 145 146 static_assert(sizeof(CowOperation) == sizeof(CowFooterOperation)); 147 148 static constexpr uint8_t kCowCopyOp = 1; 149 static constexpr uint8_t kCowReplaceOp = 2; 150 static constexpr uint8_t kCowZeroOp = 3; 151 static constexpr uint8_t kCowLabelOp = 4; 152 static constexpr uint8_t kCowClusterOp = 5; 153 static constexpr uint8_t kCowXorOp = 6; 154 static constexpr uint8_t kCowSequenceOp = 7; 155 static constexpr uint8_t kCowFooterOp = -1; 156 157 enum CowCompressionAlgorithm : uint8_t { 158 kCowCompressNone = 0, 159 kCowCompressGz = 1, 160 kCowCompressBrotli = 2, 161 kCowCompressLz4 = 3 162 }; 163 164 static constexpr uint8_t kCowReadAheadNotStarted = 0; 165 static constexpr uint8_t kCowReadAheadInProgress = 1; 166 static constexpr uint8_t kCowReadAheadDone = 2; 167 168 struct CowFooter { 169 CowFooterOperation op; 170 CowFooterData data; 171 } __attribute__((packed)); 172 173 struct ScratchMetadata { 174 // Block of data in the image that operation modifies 175 // and read-ahead thread stores the modified data 176 // in the scratch space 177 uint64_t new_block; 178 // Offset within the file to read the data 179 uint64_t file_offset; 180 } __attribute__((packed)); 181 182 struct BufferState { 183 uint8_t read_ahead_state; 184 } __attribute__((packed)); 185 186 // 2MB Scratch space used for read-ahead 187 static constexpr uint64_t BUFFER_REGION_DEFAULT_SIZE = (1ULL << 21); 188 189 std::ostream& operator<<(std::ostream& os, CowOperation const& arg); 190 191 int64_t GetNextOpOffset(const CowOperation& op, uint32_t cluster_size); 192 int64_t GetNextDataOffset(const CowOperation& op, uint32_t cluster_size); 193 194 // Ops that are internal to the Cow Format and not OTA data 195 bool IsMetadataOp(const CowOperation& op); 196 // Ops that have dependencies on old blocks, and must take care in their merge order 197 bool IsOrderedOp(const CowOperation& op); 198 199 } // namespace snapshot 200 } // namespace android 201