1 //
2 // Copyright (C) 2015 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_BOOT_CONTROL_INTERFACE_H_
18 #define UPDATE_ENGINE_COMMON_BOOT_CONTROL_INTERFACE_H_
19 
20 #include <climits>
21 #include <map>
22 #include <string>
23 #include <vector>
24 
25 #include <base/callback.h>
26 #include <base/macros.h>
27 
28 #include "update_engine/common/dynamic_partition_control_interface.h"
29 #include "update_engine/update_metadata.pb.h"
30 
31 namespace chromeos_update_engine {
32 
33 // The abstract boot control interface defines the interaction with the
34 // platform's bootloader hiding vendor-specific details from the rest of
35 // update_engine. This interface is used for controlling where the device should
36 // boot from.
37 class BootControlInterface {
38  public:
39   using Slot = unsigned int;
40 
41   static const Slot kInvalidSlot = UINT_MAX;
42 
43   virtual ~BootControlInterface() = default;
44 
45   // Return the number of update slots in the system. A system will normally
46   // have two slots, named "A" and "B" in the documentation, but sometimes
47   // images running from other media can have only one slot, like some USB
48   // image. Systems with only one slot won't be able to update.
49   virtual unsigned int GetNumSlots() const = 0;
50 
51   // Return the slot where we are running the system from. On success, the
52   // result is a number between 0 and GetNumSlots() - 1. Otherwise, log an error
53   // and return kInvalidSlot.
54   virtual Slot GetCurrentSlot() const = 0;
55 
56   // Determines the block device for the given partition name and slot number.
57   // The |slot| number must be between 0 and GetNumSlots() - 1 and the
58   // |partition_name| is a platform-specific name that identifies a partition on
59   // every slot. In order to access the dynamic partitions in the target slot,
60   // GetDynamicPartitionControl()->PreparePartitionsForUpdate() must be called
61   // (with |update| == true for the first time for a payload, and |false| for
62   // for the rest of the times) prior to calling this function.
63   // The handling may be different based on whether the partition is included
64   // in the update payload. On success, returns true; and stores the block
65   // device in |device|, if the partition is dynamic in |is_dynamic|.
66   virtual bool GetPartitionDevice(const std::string& partition_name,
67                                   Slot slot,
68                                   bool not_in_payload,
69                                   std::string* device,
70                                   bool* is_dynamic) const = 0;
71 
72   // Overload of the above function. We assume the partition is always included
73   // in the payload.
74   virtual bool GetPartitionDevice(const std::string& partition_name,
75                                   Slot slot,
76                                   std::string* device) const = 0;
77 
78   virtual std::optional<PartitionDevice> GetPartitionDevice(
79       const std::string& partition_name,
80       uint32_t slot,
81       uint32_t current_slot,
82       bool not_in_payload = false) const = 0;
83   // Returns whether the passed |slot| is marked as bootable. Returns false if
84   // the slot is invalid.
85   virtual bool IsSlotBootable(Slot slot) const = 0;
86 
87   // Mark the specified slot unbootable. No other slot flags are modified.
88   // Returns true on success.
89   virtual bool MarkSlotUnbootable(Slot slot) = 0;
90 
91   // Set the passed |slot| as the preferred boot slot. Returns whether it
92   // succeeded setting the active slot. If succeeded, on next boot the
93   // bootloader will attempt to load the |slot| marked as active. Note that this
94   // method doesn't change the value of GetCurrentSlot() on the current boot.
95   virtual bool SetActiveBootSlot(Slot slot) = 0;
96 
97   // Mark the current slot as successfully booted asynchronously. No other slot
98   // flags are modified. Returns false if it was not able to schedule the
99   // operation, otherwise, returns true and calls the |callback| with the result
100   // of the operation.
101   virtual bool MarkBootSuccessfulAsync(base::Callback<void(bool)> callback) = 0;
102 
103   // Check if |slot| is marked boot successfully.
104   virtual bool IsSlotMarkedSuccessful(Slot slot) const = 0;
105 
106   // Return the dynamic partition control interface. Never null.
107   virtual DynamicPartitionControlInterface* GetDynamicPartitionControl() = 0;
108 
109   // Return a human-readable slot name used for logging.
SlotName(Slot slot)110   static std::string SlotName(Slot slot) {
111     if (slot == kInvalidSlot)
112       return "INVALID";
113     if (slot < 26)
114       return std::string(1, 'A' + slot);
115     return "TOO_BIG";
116   }
117 
118  protected:
119   BootControlInterface() = default;
120 
121  private:
122   DISALLOW_COPY_AND_ASSIGN(BootControlInterface);
123 };
124 
125 }  // namespace chromeos_update_engine
126 
127 #endif  // UPDATE_ENGINE_COMMON_BOOT_CONTROL_INTERFACE_H_
128