1 // 2 // Copyright (C) 2018 The Android Open Source Project 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 17 #ifndef UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_ 18 #define UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_ 19 20 #include <stdint.h> 21 22 #include <memory> 23 #include <string> 24 #include <vector> 25 26 #include "update_engine/common/action.h" 27 #include "update_engine/common/cleanup_previous_update_action_delegate.h" 28 #include "update_engine/common/error_code.h" 29 #include "update_engine/common/prefs_interface.h" 30 #include "update_engine/payload_consumer/file_descriptor.h" 31 #include "update_engine/update_metadata.pb.h" 32 33 // Forware declare for libsnapshot/snapshot_writer.h 34 namespace android::snapshot { 35 class ISnapshotWriter; 36 } 37 38 namespace chromeos_update_engine { 39 40 struct PartitionDevice { 41 std::string rw_device_path; 42 std::string readonly_device_path; 43 bool is_dynamic; 44 }; 45 46 struct FeatureFlag { 47 enum class Value { NONE = 0, RETROFIT, LAUNCH }; FeatureFlagFeatureFlag48 constexpr explicit FeatureFlag(Value value) : value_(value) {} IsEnabledFeatureFlag49 constexpr bool IsEnabled() const { return value_ != Value::NONE; } IsRetrofitFeatureFlag50 constexpr bool IsRetrofit() const { return value_ == Value::RETROFIT; } IsLaunchFeatureFlag51 constexpr bool IsLaunch() const { return value_ == Value::LAUNCH; } 52 53 private: 54 Value value_; 55 }; 56 57 class BootControlInterface; 58 59 class DynamicPartitionControlInterface { 60 public: 61 virtual ~DynamicPartitionControlInterface() = default; 62 63 // Return the feature flags of dynamic partitions on this device. 64 // Return RETROFIT iff dynamic partitions is retrofitted on this device, 65 // LAUNCH iff this device is launched with dynamic partitions, 66 // NONE iff dynamic partitions is disabled on this device. 67 virtual FeatureFlag GetDynamicPartitionsFeatureFlag() = 0; 68 69 // Return the feature flags of Virtual A/B on this device. 70 virtual FeatureFlag GetVirtualAbFeatureFlag() = 0; 71 // Return the feature flags of Virtual A/B Compression on this device. 72 // This function will tell you if current device supports VABC. However, it 73 // DOES NOT tell you if VABC is used for current OTA update. For that, use 74 // UpdateUsesSnapshotCompression. 75 virtual FeatureFlag GetVirtualAbCompressionFeatureFlag() = 0; 76 // Return the feature flag for Virtual AB Compression XOR 77 virtual FeatureFlag GetVirtualAbCompressionXorFeatureFlag() = 0; 78 79 // Attempt to optimize |operation|. 80 // If successful, |optimized| contains an operation with extents that 81 // needs to be written. 82 // If failed, no optimization is available, and caller should perform 83 // |operation| directly. 84 // |partition_name| should not have the slot suffix; implementation of 85 // DynamicPartitionControlInterface checks partition at the target slot 86 // previously set with PreparePartitionsForUpdate(). 87 virtual bool OptimizeOperation(const std::string& partition_name, 88 const InstallOperation& operation, 89 InstallOperation* optimized) = 0; 90 91 // Do necessary cleanups before destroying the object. 92 virtual void Cleanup() = 0; 93 94 // Prepare all partitions for an update specified in |manifest|. 95 // This is needed before calling MapPartitionOnDeviceMapper(), otherwise the 96 // device would be mapped in an inconsistent way. 97 // If |update| is set, create snapshots and writes super partition metadata. 98 // If |required_size| is not null and call fails due to insufficient space, 99 // |required_size| will be set to total free space required on userdata 100 // partition to apply the update. Otherwise (call succeeds, or fails 101 // due to other errors), |required_size| is set to zero. 102 virtual bool PreparePartitionsForUpdate(uint32_t source_slot, 103 uint32_t target_slot, 104 const DeltaArchiveManifest& manifest, 105 bool update, 106 uint64_t* required_size) = 0; 107 108 // After writing to new partitions, before rebooting into the new slot, call 109 // this function to indicate writes to new partitions are done. 110 virtual bool FinishUpdate(bool powerwash_required) = 0; 111 112 // Get an action to clean up previous update. 113 // Return NoOpAction on non-Virtual A/B devices. 114 // Before applying the next update, run this action to clean up previous 115 // update files. This function blocks until delta files are merged into 116 // current OS partitions and finished cleaning up. 117 // - If successful, action completes with kSuccess. 118 // - If any error, but caller should retry after reboot, action completes with 119 // kError. 120 // - If any irrecoverable failures, action completes with kDeviceCorrupted. 121 // 122 // See ResetUpdate for differences between CleanuPreviousUpdateAction and 123 // ResetUpdate. 124 virtual std::unique_ptr<AbstractAction> GetCleanupPreviousUpdateAction( 125 BootControlInterface* boot_control, 126 PrefsInterface* prefs, 127 CleanupPreviousUpdateActionDelegateInterface* delegate) = 0; 128 129 // Called after an unwanted payload has been successfully applied and the 130 // device has not yet been rebooted. 131 // 132 // For snapshot updates (Virtual A/B), it calls 133 // DeltaPerformer::ResetUpdateProgress(false /* quick */) and 134 // frees previously allocated space; the next update will need to be 135 // started over. 136 // 137 // Note: CleanupPreviousUpdateAction does not do anything if an update is in 138 // progress, while ResetUpdate() forcefully free previously 139 // allocated space for snapshot updates. 140 virtual bool ResetUpdate(PrefsInterface* prefs) = 0; 141 142 // Reads the dynamic partitions metadata from the given slot, and puts the 143 // name of the dynamic partitions with the current suffix to |partitions|. 144 // Returns true on success. 145 virtual bool ListDynamicPartitionsForSlot( 146 uint32_t slot, 147 uint32_t current_slot, 148 std::vector<std::string>* partitions) = 0; 149 150 // Finds a possible location that list all block devices by name; and puts 151 // the result in |path|. Returns true on success. 152 // Sample result: /dev/block/by-name/ 153 virtual bool GetDeviceDir(std::string* path) = 0; 154 155 // Verifies that the untouched dynamic partitions in the target metadata have 156 // the same extents as the source metadata. 157 virtual bool VerifyExtentsForUntouchedPartitions( 158 uint32_t source_slot, 159 uint32_t target_slot, 160 const std::vector<std::string>& partitions) = 0; 161 // Partition name is expected to be unsuffixed. e.g. system, vendor 162 // Return an interface to write to a snapshoted partition. 163 // If `is_append` is false, then existing COW data will be overwritten. 164 // Otherwise the cow writer will be opened on APPEND mode, existing COW data 165 // is preserved. 166 virtual std::unique_ptr<android::snapshot::ISnapshotWriter> OpenCowWriter( 167 const std::string& unsuffixed_partition_name, 168 const std::optional<std::string>&, 169 bool is_append = false) = 0; 170 // Open a general purpose FD capable to reading and writing to COW. Note that 171 // writes must be block aligned. 172 virtual std::unique_ptr<FileDescriptor> OpenCowFd( 173 const std::string& unsuffixed_partition_name, 174 const std::optional<std::string>&, 175 bool is_append = false) = 0; 176 177 virtual bool IsDynamicPartition(const std::string& part_name, 178 uint32_t slot) = 0; 179 180 // Create virtual block devices for all partitions. 181 virtual bool MapAllPartitions() = 0; 182 // Unmap virtual block devices for all partitions. 183 virtual bool UnmapAllPartitions() = 0; 184 185 // Return if snapshot compression is enabled for this update. 186 // This function should only be called after preparing for an update 187 // (PreparePartitionsForUpdate), and before merging 188 // (see GetCleanupPreviousUpdateAction and CleanupPreviousUpdateAction) or 189 // resetting it (ResetUpdate). 190 // 191 // To know if the device supports snapshot compression by itself, use 192 // GetVirtualAbCompressionFeatureFlag 193 virtual bool UpdateUsesSnapshotCompression() = 0; 194 }; 195 196 } // namespace chromeos_update_engine 197 198 #endif // UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_ 199