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