1 /* 2 * Copyright (C) 2011 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 _RECOVERY_DEVICE_H 18 #define _RECOVERY_DEVICE_H 19 20 #include <stddef.h> 21 22 #include <memory> 23 #include <optional> 24 #include <string> 25 #include <vector> 26 27 // Forward declaration to avoid including "ui.h". 28 class RecoveryUI; 29 30 class BootState; 31 32 class Device { 33 public: 34 static constexpr const int kNoAction = -1; 35 static constexpr const int kHighlightUp = -2; 36 static constexpr const int kHighlightDown = -3; 37 static constexpr const int kInvokeItem = -4; 38 39 // ENTER vs REBOOT: The latter will trigger a reboot that goes through bootloader, which allows 40 // using a new bootloader / recovery image if applicable. For example, REBOOT_RESCUE goes from 41 // rescue -> bootloader -> rescue, whereas ENTER_RESCUE switches from recovery -> rescue 42 // directly. 43 enum BuiltinAction { 44 NO_ACTION = 0, 45 REBOOT = 1, 46 APPLY_SDCARD = 2, 47 // APPLY_CACHE was 3. 48 APPLY_ADB_SIDELOAD = 4, 49 WIPE_DATA = 5, 50 WIPE_CACHE = 6, 51 REBOOT_BOOTLOADER = 7, 52 SHUTDOWN = 8, 53 VIEW_RECOVERY_LOGS = 9, 54 MOUNT_SYSTEM = 10, 55 RUN_GRAPHICS_TEST = 11, 56 RUN_LOCALE_TEST = 12, 57 KEY_INTERRUPTED = 13, 58 ENTER_FASTBOOT = 14, 59 ENTER_RECOVERY = 15, 60 ENTER_RESCUE = 16, 61 REBOOT_FASTBOOT = 17, 62 REBOOT_RECOVERY = 18, 63 REBOOT_RESCUE = 19, 64 REBOOT_FROM_FASTBOOT = 20, 65 SHUTDOWN_FROM_FASTBOOT = 21, 66 }; 67 68 explicit Device(RecoveryUI* ui); ~Device()69 virtual ~Device() {} 70 71 // Returns a raw pointer to the RecoveryUI object. GetUI()72 virtual RecoveryUI* GetUI() { 73 return ui_.get(); 74 } 75 76 // Resets the UI object to the given UI. Used to override the default UI in case initialization 77 // failed, or we want a different UI for some reason. The device object will take the ownership. ResetUI(RecoveryUI * ui)78 virtual void ResetUI(RecoveryUI* ui) { 79 ui_.reset(ui); 80 } 81 82 // Called before recovery mode started up, to perform whatever device-specific recovery mode 83 // preparation as needed. PreRecovery()84 virtual void PreRecovery() {} 85 86 // Called when recovery starts up (after the UI has been obtained and initialized and after the 87 // arguments have been parsed, but before anything else). StartRecovery()88 virtual void StartRecovery() {} 89 90 // Called before fastboot mode is started up, to perform whatever device-specific fastboot mode 91 // preparation as needed. PreFastboot()92 virtual void PreFastboot() {} 93 94 // Called when fastboot starts up (after the UI has been obtained and initialized and after the 95 // arguments have been parsed, but before anything else). StartFastboot()96 virtual void StartFastboot() {} 97 98 // Called from the main thread when recovery is at the main menu and waiting for input, and a key 99 // is pressed. (Note that "at" the main menu does not necessarily mean the menu is visible; 100 // recovery will be at the main menu with it invisible after an unsuccessful operation, such as 101 // failed to install an OTA package, or if recovery is started with no command.) 102 // 103 // 'key' is the code of the key just pressed. (You can call IsKeyPressed() on the RecoveryUI 104 // object you returned from GetUI() if you want to find out if other keys are held down.) 105 // 106 // 'visible' is true if the menu is visible. 107 // 108 // Returns one of the defined constants below in order to: 109 // - move the menu highlight (kHighlight{Up,Down}: negative value) 110 // - invoke the highlighted item (kInvokeItem: negative value) 111 // - do nothing (kNoAction: negative value) 112 // - invoke a specific action (a menu position: non-negative value) 113 virtual int HandleMenuKey(int key, bool visible); 114 115 // Returns the list of menu items (a vector of strings). The menu_position passed to 116 // InvokeMenuItem() will correspond to the indexes into this array. 117 virtual const std::vector<std::string>& GetMenuItems(); 118 119 // Performs a recovery action selected from the menu. 'menu_position' will be the index of the 120 // selected menu item, or a non-negative value returned from HandleMenuKey(). The menu will be 121 // hidden when this is called; implementations can call GetUI()->Print() to print information to 122 // the screen. If the menu position is one of the builtin actions, you can just return the 123 // corresponding enum value. If it is an action specific to your device, you actually perform it 124 // here and return NO_ACTION. 125 virtual BuiltinAction InvokeMenuItem(size_t menu_position); 126 127 // Removes the menu item for the given action. This allows tailoring the menu based on the 128 // runtime info, such as the availability of /cache or /sdcard. 129 virtual void RemoveMenuItemForAction(Device::BuiltinAction action); 130 131 // Called before and after we do a wipe data/factory reset operation, either via a reboot from the 132 // main system with the --wipe_data flag, or when the user boots into recovery image manually and 133 // selects the option from the menu, to perform whatever device-specific wiping actions as needed. 134 // Returns true on success; returning false from PreWipeData will prevent the regular wipe, and 135 // returning false from PostWipeData will cause the wipe to be considered a failure. PreWipeData()136 virtual bool PreWipeData() { 137 return true; 138 } 139 PostWipeData()140 virtual bool PostWipeData() { 141 return true; 142 } 143 144 void SetBootState(const BootState* state); 145 // The getters for reason and stage may return std::nullopt until StartRecovery() is called. It's 146 // the caller's responsibility to perform the check and handle the exception. 147 std::optional<std::string> GetReason() const; 148 std::optional<std::string> GetStage() const; 149 150 private: 151 // The RecoveryUI object that should be used to display the user interface for this device. 152 std::unique_ptr<RecoveryUI> ui_; 153 const BootState* boot_state_{ nullptr }; 154 }; 155 156 // Disable name mangling, as this function will be loaded via dlsym(3). 157 extern "C" { 158 159 // The device-specific library must define this function (or the default one will be used, if there 160 // is no device-specific library). It returns the Device object that recovery should use. 161 Device* make_device(); 162 } 163 164 #endif // _DEVICE_H 165