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 ICowWriter;
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,
110                                           ErrorCode* error = nullptr) = 0;
111 
112   // After writing to new partitions, before rebooting into the new slot, call
113   // this function to indicate writes to new partitions are done.
114   virtual bool FinishUpdate(bool powerwash_required) = 0;
115 
116   // Get an action to clean up previous update.
117   // Return NoOpAction on non-Virtual A/B devices.
118   // Before applying the next update, run this action to clean up previous
119   // update files. This function blocks until delta files are merged into
120   // current OS partitions and finished cleaning up.
121   // - If successful, action completes with kSuccess.
122   // - If any error, but caller should retry after reboot, action completes with
123   //   kError.
124   // - If any irrecoverable failures, action completes with kDeviceCorrupted.
125   //
126   // See ResetUpdate for differences between CleanuPreviousUpdateAction and
127   // ResetUpdate.
128   virtual std::unique_ptr<AbstractAction> GetCleanupPreviousUpdateAction(
129       BootControlInterface* boot_control,
130       PrefsInterface* prefs,
131       CleanupPreviousUpdateActionDelegateInterface* delegate) = 0;
132 
133   // Called after an unwanted payload has been successfully applied and the
134   // device has not yet been rebooted.
135   //
136   // For snapshot updates (Virtual A/B), it calls
137   // DeltaPerformer::ResetUpdateProgress(false /* quick */) and
138   // frees previously allocated space; the next update will need to be
139   // started over.
140   //
141   // Note: CleanupPreviousUpdateAction does not do anything if an update is in
142   // progress, while ResetUpdate() forcefully free previously
143   // allocated space for snapshot updates.
144   virtual bool ResetUpdate(PrefsInterface* prefs) = 0;
145 
146   // Reads the dynamic partitions metadata from the given slot, and puts the
147   // name of the dynamic partitions with the current suffix to |partitions|.
148   // Returns true on success.
149   virtual bool ListDynamicPartitionsForSlot(
150       uint32_t slot,
151       uint32_t current_slot,
152       std::vector<std::string>* partitions) = 0;
153 
154   // Finds a possible location that list all block devices by name; and puts
155   // the result in |path|. Returns true on success.
156   // Sample result: /dev/block/by-name/
157   virtual bool GetDeviceDir(std::string* path) = 0;
158 
159   // Verifies that the untouched dynamic partitions in the target metadata have
160   // the same extents as the source metadata.
161   virtual bool VerifyExtentsForUntouchedPartitions(
162       uint32_t source_slot,
163       uint32_t target_slot,
164       const std::vector<std::string>& partitions) = 0;
165   // Partition name is expected to be unsuffixed. e.g. system, vendor
166   // Return an interface to write to a snapshoted partition.
167   // If `is_append` is false, then existing COW data will be overwritten.
168   // Otherwise the cow writer will be opened on APPEND mode, existing COW data
169   // is preserved.
170   virtual std::unique_ptr<android::snapshot::ICowWriter> OpenCowWriter(
171       const std::string& unsuffixed_partition_name,
172       const std::optional<std::string>&,
173       std::optional<uint64_t> label) = 0;
174   // Open a general purpose FD capable to reading and writing to COW. Note that
175   // writes must be block aligned.
176   virtual std::unique_ptr<FileDescriptor> OpenCowFd(
177       const std::string& unsuffixed_partition_name,
178       const std::optional<std::string>&,
179       bool is_append = false) = 0;
180 
181   virtual bool IsDynamicPartition(const std::string& part_name,
182                                   uint32_t slot) = 0;
183 
184   // Create virtual block devices for all partitions.
185   virtual bool MapAllPartitions() = 0;
186   // Unmap virtual block devices for all partitions.
187   virtual bool UnmapAllPartitions() = 0;
188 
189   // Return if snapshot compression is enabled for this update.
190   // This function should only be called after preparing for an update
191   // (PreparePartitionsForUpdate), and before merging
192   // (see GetCleanupPreviousUpdateAction and CleanupPreviousUpdateAction) or
193   // resetting it (ResetUpdate).
194   //
195   // To know if the device supports snapshot compression by itself, use
196   // GetVirtualAbCompressionFeatureFlag
197   virtual bool UpdateUsesSnapshotCompression() = 0;
198 };
199 
200 }  // namespace chromeos_update_engine
201 
202 #endif  // UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_
203