blob: 76166f09d71ca9c1ef1a3d4366e0dbbe9eb95852 [file] [log] [blame]
Doug Zongkerdaefc1d2011-10-31 09:34:15 -07001/*
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
Tao Bao1fe1afe2018-05-01 15:56:05 -070020#include <stddef.h>
21
Tao Bao551d2c32018-05-09 20:53:13 -070022#include <memory>
Tianjie Xub63a2212019-07-29 14:21:49 -070023#include <optional>
Tao Bao1fe1afe2018-05-01 15:56:05 -070024#include <string>
25#include <vector>
26
Tao Baoc16fd8a2018-04-30 17:12:03 -070027// Forward declaration to avoid including "ui.h".
28class RecoveryUI;
Doug Zongkerdaefc1d2011-10-31 09:34:15 -070029
Tianjie Xub63a2212019-07-29 14:21:49 -070030class BootState;
31
Doug Zongkerdaefc1d2011-10-31 09:34:15 -070032class Device {
Tao Baofc5499f2017-02-23 19:06:53 -080033 public:
Tao Bao1fe1afe2018-05-01 15:56:05 -070034 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
Tao Baod9cb0142019-04-23 11:46:25 -070039 // 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.
Tao Bao1fe1afe2018-05-01 15:56:05 -070043 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,
Jerry Zhangb76af932018-05-22 12:08:35 -070057 KEY_INTERRUPTED = 13,
Hridya Valsaraju20c81b32018-07-27 22:09:12 -070058 ENTER_FASTBOOT = 14,
59 ENTER_RECOVERY = 15,
Tao Baoc6dc3252019-04-16 14:22:25 -070060 ENTER_RESCUE = 16,
Tao Baod9cb0142019-04-23 11:46:25 -070061 REBOOT_FASTBOOT = 17,
62 REBOOT_RECOVERY = 18,
63 REBOOT_RESCUE = 19,
Mark Salyzyn488cc052019-05-20 10:36:16 -070064 REBOOT_FROM_FASTBOOT = 20,
65 SHUTDOWN_FROM_FASTBOOT = 21,
Tao Bao1fe1afe2018-05-01 15:56:05 -070066 };
67
Tao Baoe5d2c252018-05-09 11:05:44 -070068 explicit Device(RecoveryUI* ui);
Tao Baofc5499f2017-02-23 19:06:53 -080069 virtual ~Device() {}
Doug Zongkerdaefc1d2011-10-31 09:34:15 -070070
Tao Bao551d2c32018-05-09 20:53:13 -070071 // Returns a raw pointer to the RecoveryUI object.
Tao Baofc5499f2017-02-23 19:06:53 -080072 virtual RecoveryUI* GetUI() {
Tao Bao551d2c32018-05-09 20:53:13 -070073 return ui_.get();
Tao Baofc5499f2017-02-23 19:06:53 -080074 }
Doug Zongkerdaefc1d2011-10-31 09:34:15 -070075
Tao Bao551d2c32018-05-09 20:53:13 -070076 // 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.
78 virtual void ResetUI(RecoveryUI* ui) {
79 ui_.reset(ui);
Jerry Zhang2dea53e2018-05-02 17:15:03 -070080 }
81
Hongguang Chen04267272020-04-21 20:58:04 -070082 // Called before recovery mode started up, to perform whatever device-specific recovery mode
83 // preparation as needed.
84 virtual void PreRecovery() {}
85
Tao Baofc5499f2017-02-23 19:06:53 -080086 // 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).
Tianjie Xu8f397302018-08-20 13:40:47 -070088 virtual void StartRecovery() {}
Doug Zongkerdaefc1d2011-10-31 09:34:15 -070089
Hongguang Chen04267272020-04-21 20:58:04 -070090 // Called before fastboot mode is started up, to perform whatever device-specific fastboot mode
91 // preparation as needed.
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).
96 virtual void StartFastboot() {}
97
Tao Baofc5499f2017-02-23 19:06:53 -080098 // 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;
Tao Bao551d2c32018-05-09 20:53:13 -0700100 // 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.)
Tao Baofc5499f2017-02-23 19:06:53 -0800102 //
103 // 'key' is the code of the key just pressed. (You can call IsKeyPressed() on the RecoveryUI
Tao Bao551d2c32018-05-09 20:53:13 -0700104 // object you returned from GetUI() if you want to find out if other keys are held down.)
Tao Baofc5499f2017-02-23 19:06:53 -0800105 //
106 // 'visible' is true if the menu is visible.
107 //
108 // Returns one of the defined constants below in order to:
Tao Bao1fe1afe2018-05-01 15:56:05 -0700109 // - 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)
Tao Baofc5499f2017-02-23 19:06:53 -0800113 virtual int HandleMenuKey(int key, bool visible);
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700114
Tao Bao1fe1afe2018-05-01 15:56:05 -0700115 // Returns the list of menu items (a vector of strings). The menu_position passed to
Tao Bao551d2c32018-05-09 20:53:13 -0700116 // InvokeMenuItem() will correspond to the indexes into this array.
Tao Bao1fe1afe2018-05-01 15:56:05 -0700117 virtual const std::vector<std::string>& GetMenuItems();
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700118
Tao Bao1fe1afe2018-05-01 15:56:05 -0700119 // 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
Tao Baobc982a42019-03-29 15:43:09 -0700121 // 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
Tao Baofc5499f2017-02-23 19:06:53 -0800123 // corresponding enum value. If it is an action specific to your device, you actually perform it
124 // here and return NO_ACTION.
Tao Bao1fe1afe2018-05-01 15:56:05 -0700125 virtual BuiltinAction InvokeMenuItem(size_t menu_position);
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700126
Tao Baoe5d2c252018-05-09 11:05:44 -0700127 // 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
Tao Baofc5499f2017-02-23 19:06:53 -0800131 // 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.
136 virtual bool PreWipeData() {
137 return true;
138 }
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700139
Tao Baofc5499f2017-02-23 19:06:53 -0800140 virtual bool PostWipeData() {
141 return true;
142 }
143
Tianjie Xub63a2212019-07-29 14:21:49 -0700144 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
Tao Baofc5499f2017-02-23 19:06:53 -0800150 private:
Tao Bao551d2c32018-05-09 20:53:13 -0700151 // The RecoveryUI object that should be used to display the user interface for this device.
152 std::unique_ptr<RecoveryUI> ui_;
Tianjie Xub63a2212019-07-29 14:21:49 -0700153 const BootState* boot_state_{ nullptr };
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700154};
155
Tao Bao42c45e22018-07-31 09:37:12 -0700156// Disable name mangling, as this function will be loaded via dlsym(3).
157extern "C" {
158
Tao Baofc5499f2017-02-23 19:06:53 -0800159// 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.
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700161Device* make_device();
Tao Bao42c45e22018-07-31 09:37:12 -0700162}
Doug Zongkerdaefc1d2011-10-31 09:34:15 -0700163
164#endif // _DEVICE_H