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/update_metadata.pb.h"
30 
31 namespace chromeos_update_engine {
32 
33 struct FeatureFlag {
34   enum class Value { NONE = 0, RETROFIT, LAUNCH };
FeatureFlagFeatureFlag35   constexpr explicit FeatureFlag(Value value) : value_(value) {}
IsEnabledFeatureFlag36   constexpr bool IsEnabled() const { return value_ != Value::NONE; }
IsRetrofitFeatureFlag37   constexpr bool IsRetrofit() const { return value_ == Value::RETROFIT; }
IsLaunchFeatureFlag38   constexpr bool IsLaunch() const { return value_ == Value::LAUNCH; }
39 
40  private:
41   Value value_;
42 };
43 
44 class BootControlInterface;
45 class PrefsInterface;
46 
47 class DynamicPartitionControlInterface {
48  public:
49   virtual ~DynamicPartitionControlInterface() = default;
50 
51   // Return the feature flags of dynamic partitions on this device.
52   // Return RETROFIT iff dynamic partitions is retrofitted on this device,
53   //        LAUNCH iff this device is launched with dynamic partitions,
54   //        NONE iff dynamic partitions is disabled on this device.
55   virtual FeatureFlag GetDynamicPartitionsFeatureFlag() = 0;
56 
57   // Return the feature flags of Virtual A/B on this device.
58   virtual FeatureFlag GetVirtualAbFeatureFlag() = 0;
59 
60   // Attempt to optimize |operation|.
61   // If successful, |optimized| contains an operation with extents that
62   // needs to be written.
63   // If failed, no optimization is available, and caller should perform
64   // |operation| directly.
65   // |partition_name| should not have the slot suffix; implementation of
66   // DynamicPartitionControlInterface checks partition at the target slot
67   // previously set with PreparePartitionsForUpdate().
68   virtual bool OptimizeOperation(const std::string& partition_name,
69                                  const InstallOperation& operation,
70                                  InstallOperation* optimized) = 0;
71 
72   // Do necessary cleanups before destroying the object.
73   virtual void Cleanup() = 0;
74 
75   // Prepare all partitions for an update specified in |manifest|.
76   // This is needed before calling MapPartitionOnDeviceMapper(), otherwise the
77   // device would be mapped in an inconsistent way.
78   // If |update| is set, create snapshots and writes super partition metadata.
79   // If |required_size| is not null and call fails due to insufficient space,
80   // |required_size| will be set to total free space required on userdata
81   // partition to apply the update. Otherwise (call succeeds, or fails
82   // due to other errors), |required_size| is set to zero.
83   virtual bool PreparePartitionsForUpdate(uint32_t source_slot,
84                                           uint32_t target_slot,
85                                           const DeltaArchiveManifest& manifest,
86                                           bool update,
87                                           uint64_t* required_size) = 0;
88 
89   // After writing to new partitions, before rebooting into the new slot, call
90   // this function to indicate writes to new partitions are done.
91   virtual bool FinishUpdate(bool powerwash_required) = 0;
92 
93   // Get an action to clean up previous update.
94   // Return NoOpAction on non-Virtual A/B devices.
95   // Before applying the next update, run this action to clean up previous
96   // update files. This function blocks until delta files are merged into
97   // current OS partitions and finished cleaning up.
98   // - If successful, action completes with kSuccess.
99   // - If any error, but caller should retry after reboot, action completes with
100   //   kError.
101   // - If any irrecoverable failures, action completes with kDeviceCorrupted.
102   //
103   // See ResetUpdate for differences between CleanuPreviousUpdateAction and
104   // ResetUpdate.
105   virtual std::unique_ptr<AbstractAction> GetCleanupPreviousUpdateAction(
106       BootControlInterface* boot_control,
107       PrefsInterface* prefs,
108       CleanupPreviousUpdateActionDelegateInterface* delegate) = 0;
109 
110   // Called after an unwanted payload has been successfully applied and the
111   // device has not yet been rebooted.
112   //
113   // For snapshot updates (Virtual A/B), it calls
114   // DeltaPerformer::ResetUpdateProgress(false /* quick */) and
115   // frees previously allocated space; the next update will need to be
116   // started over.
117   //
118   // Note: CleanupPreviousUpdateAction does not do anything if an update is in
119   // progress, while ResetUpdate() forcefully free previously
120   // allocated space for snapshot updates.
121   virtual bool ResetUpdate(PrefsInterface* prefs) = 0;
122 
123   // Reads the dynamic partitions metadata from the current slot, and puts the
124   // name of the dynamic partitions with the current suffix to |partitions|.
125   // Returns true on success.
126   virtual bool ListDynamicPartitionsForSlot(
127       uint32_t current_slot, std::vector<std::string>* partitions) = 0;
128 
129   // Finds a possible location that list all block devices by name; and puts
130   // the result in |path|. Returns true on success.
131   // Sample result: /dev/block/by-name/
132   virtual bool GetDeviceDir(std::string* path) = 0;
133 
134   // Verifies that the untouched dynamic partitions in the target metadata have
135   // the same extents as the source metadata.
136   virtual bool VerifyExtentsForUntouchedPartitions(
137       uint32_t source_slot,
138       uint32_t target_slot,
139       const std::vector<std::string>& partitions) = 0;
140 };
141 
142 }  // namespace chromeos_update_engine
143 
144 #endif  // UPDATE_ENGINE_COMMON_DYNAMIC_PARTITION_CONTROL_INTERFACE_H_
145