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 // Returns whether userspace snapshots are enabled on the device, but not 79 // whether they're enabled for the update. 80 virtual FeatureFlag GetVirtualAbUserspaceSnapshotsFeatureFlag() = 0; 81 82 // Attempt to optimize |operation|. 83 // If successful, |optimized| contains an operation with extents that 84 // needs to be written. 85 // If failed, no optimization is available, and caller should perform 86 // |operation| directly. 87 // |partition_name| should not have the slot suffix; implementation of 88 // DynamicPartitionControlInterface checks partition at the target slot 89 // previously set with PreparePartitionsForUpdate(). 90 virtual bool OptimizeOperation(const std::string& partition_name, 91 const InstallOperation& operation, 92 InstallOperation* optimized) = 0; 93 94 // Do necessary cleanups before destroying the object. 95 virtual void Cleanup() = 0; 96 97 // Prepare all partitions for an update specified in |manifest|. 98 // This is needed before calling MapPartitionOnDeviceMapper(), otherwise the 99 // device would be mapped in an inconsistent way. 100 // If |update| is set, create snapshots and writes super partition metadata. 101 // If |required_size| is not null and call fails due to insufficient space, 102 // |required_size| will be set to total free space required on userdata 103 // partition to apply the update. Otherwise (call succeeds, or fails 104 // due to other errors), |required_size| is set to zero. 105 virtual bool PreparePartitionsForUpdate(uint32_t source_slot, 106 uint32_t target_slot, 107 const DeltaArchiveManifest& manifest, 108 bool update, 109 uint64_t* required_size) = 0; 110 111 // After writing to new partitions, before rebooting into the new slot, call 112 // this function to indicate writes to new partitions are done. 113 virtual bool FinishUpdate(bool powerwash_required) = 0; 114 115 // Get an action to clean up previous update. 116 // Return NoOpAction on non-Virtual A/B devices. 117 // Before applying the next update, run this action to clean up previous 118 // update files. This function blocks until delta files are merged into 119 // current OS partitions and finished cleaning up. 120 // - If successful, action completes with kSuccess. 121 // - If any error, but caller should retry after reboot, action completes with 122 // kError. 123 // - If any irrecoverable failures, action completes with kDeviceCorrupted. 124 // 125 // See ResetUpdate for differences between CleanuPreviousUpdateAction and 126 // ResetUpdate. 127 virtual std::unique_ptr<AbstractAction> GetCleanupPreviousUpdateAction( 128 BootControlInterface* boot_control, 129 PrefsInterface* prefs, 130 CleanupPreviousUpdateActionDelegateInterface* delegate) = 0; 131 132 // Called after an unwanted payload has been successfully applied and the 133 // device has not yet been rebooted. 134 // 135 // For snapshot updates (Virtual A/B), it calls 136 // DeltaPerformer::ResetUpdateProgress(false /* quick */) and 137 // frees previously allocated space; the next update will need to be 138 // started over. 139 // 140 // Note: CleanupPreviousUpdateAction does not do anything if an update is in 141 // progress, while ResetUpdate() forcefully free previously 142 // allocated space for snapshot updates. 143 virtual bool ResetUpdate(PrefsInterface* prefs) = 0; 144 145 // Reads the dynamic partitions metadata from the given slot, and puts the 146 // name of the dynamic partitions with the current suffix to |partitions|. 147 // Returns true on success. 148 virtual bool ListDynamicPartitionsForSlot( 149 uint32_t slot, 150 uint32_t current_slot, 151 std::vector<std::string>* partitions) = 0; 152 153 // Finds a possible location that list all block devices by name; and puts 154 // the result in |path|. Returns true on success. 155 // Sample result: /dev/block/by-name/ 156 virtual bool GetDeviceDir(std::string* path) = 0; 157 158 // Verifies that the untouched dynamic partitions in the target metadata have 159 // the same extents as the source metadata. 160 virtual bool VerifyExtentsForUntouchedPartitions( 161 uint32_t source_slot, 162 uint32_t target_slot, 163 const std::vector<std::string>& partitions) = 0; 164 // Partition name is expected to be unsuffixed. e.g. system, vendor 165 // Return an interface to write to a snapshoted partition. 166 // If `is_append` is false, then existing COW data will be overwritten. 167 // Otherwise the cow writer will be opened on APPEND mode, existing COW data 168 // is preserved. 169 virtual std::unique_ptr<android::snapshot::ISnapshotWriter> OpenCowWriter( 170 const std::string& unsuffixed_partition_name, 171 const std::optional<std::string>&, 172 bool is_append = false) = 0; 173 // Open a general purpose FD capable to reading and writing to COW. Note that 174 // writes must be block aligned. 175 virtual std::unique_ptr<FileDescriptor> OpenCowFd( 176 const std::string& unsuffixed_partition_name, 177 const std::optional<std::string>&, 178 bool is_append = false) = 0; 179 180 virtual bool IsDynamicPartition(const std::string& part_name, 181 uint32_t slot) = 0; 182 183 // Create virtual block devices for all partitions. 184 virtual bool MapAllPartitions() = 0; 185 // Unmap virtual block devices for all partitions. 186 virtual bool UnmapAllPartitions() = 0; 187 188 // Return if snapshot compression is enabled for this update. 189 // This function should only be called after preparing for an update 190 // (PreparePartitionsForUpdate), and before merging 191 // (see GetCleanupPreviousUpdateAction and CleanupPreviousUpdateAction) or 192 // resetting it (ResetUpdate). 193 // 194 // To know if the device supports snapshot compression by itself, use 195 // GetVirtualAbCompressionFeatureFlag 196 virtual bool UpdateUsesSnapshotCompression() = 0; 197 }; 198 199 } // namespace chromeos_update_engine 200 201 #endif // UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_ 202