Recovery模式的命令行参数

概要

本文描述Android应用层要进入recovery模式时，需要设定参数的方式、以及参数的格式。

应用层的调用场景

有如下的场景需要让手机重启进入recovery模式：

系统升级；
恢复出厂设置

RecoverySystem.java

// \frameworks\base\core\java\android\os\RecoverySystem.java
* fails, or if the reboot itself fails.
*/
public static void installPackage(Context context, File packageFile)
throws IOException {
String filename = packageFile.getCanonicalPath();
Log.w(TAG, "!!! REBOOTING TO INSTALL " + filename + " !!!");
String arg = "--update_package=" + filename +
"\n--locale=" + Locale.getDefault().toString();
bootCommand(context, arg);
}

/**
* Reboots the device and wipes the user data partition.  This is
* sometimes called a "factory reset", which is something of a
* misnomer because the system partition is not restored to its
* factory state.
* Requires the {@link android.Manifest.permission#REBOOT} permission.
*
* @param context  the Context to use
*
* @throws IOException  if writing the recovery command file
* fails, or if the reboot itself fails.
*/
public static void rebootWipeUserData(Context context) throws IOException {
final ConditionVariable condition = new ConditionVariable();

Intent intent = new Intent("android.intent.action.MASTER_CLEAR_NOTIFICATION");
context.sendOrderedBroadcastAsUser(intent, UserHandle.OWNER,
android.Manifest.permission.MASTER_CLEAR,
new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
condition.open();
}
}, null, 0, null, null);

// Block until the ordered broadcast has completed.
condition.block();

bootCommand(context, "--wipe_data\n--locale=" + Locale.getDefault().toString());
}

/**
* Reboot into the recovery system to wipe the /cache partition.
* @throws IOException if something goes wrong.
*/
public static void rebootWipeCache(Context context) throws IOException {
bootCommand(context, "--wipe_cache\n--locale=" + Locale.getDefault().toString());
}

/**
* Reboot into the recovery system with the supplied argument.
* @param arg to pass to the recovery utility.
* @throws IOException if something goes wrong.
*/
private static void bootCommand(Context context, String arg) throws IOException {
RECOVERY_DIR.mkdirs();  // In case we need it
COMMAND_FILE.delete();  // In case it's not writable
LOG_FILE.delete();

FileWriter command = new FileWriter(COMMAND_FILE);
try {
command.write(arg);
command.write("\n");
} finally {
command.close();
}

// Having written the command file, go ahead and reboot
PowerManager pm = (PowerManager) context.getSystemService(Context.POWER_SERVICE);
pm.reboot("recovery");

throw new IOException("Reboot failed (no permissions?)");
}

这里包括了：

installPackage：系统升级，比如FOTA、组合按键进入recovery，等等
rebootWipeUserData：重启用于擦除用户数据（恢复出厂设置）；
rebootWipeCache：擦除cache分区

所有这些都通过COMMAND_FILE（/cache/recovery/command）文件来给recovery传递命令行参数。

command文件的格式

如同上面代码所描述的，command文件中，每个参数占用一行；每个参数本身采用--parName=parValue的格式。如：

--wipe_data
--locale=en

因为Android底层是Linux，所以换行使用的是\n，而不是\r\n。——参考上面的java代码。当然，recovery为了提高可靠性，增加了容错处理。下面是recovery.cpp中的处理过程：

// \bootable\recovery\recovery.cpp

// --- if that doesn't work, try the command file
if (*argc <= 1) {
FILE *fp = fopen_path(COMMAND_FILE, "r");
if (fp != NULL) {
char *token;
char *argv0 = (*argv)[0];
*argv = (char **) malloc(sizeof(char *) * MAX_ARGS);
(*argv)[0] = argv0;  // use the same program name

char buf[MAX_ARG_LENGTH];
for (*argc = 1; *argc < MAX_ARGS; ++*argc) {
if (!fgets(buf, sizeof(buf), fp)) break;
token = strtok(buf, "\r\n");
if (token != NULL) {
(*argv)[*argc] = strdup(token);  // Strip newline.
} else {
--*argc;
}
}

check_and_fclose(fp, COMMAND_FILE);
LOGI("Got arguments from %s\n", COMMAND_FILE);
}
}

recovery支持的命令行参数

recovery支持的参数由recovery.cpp中的OPTIONS来定义：

static const struct option OPTIONS[] = {
{ "send_intent", required_argument, NULL, 's' },
{ "update_package", required_argument, NULL, 'u' },
{ "wipe_data", no_argument, NULL, 'w' },
{ "wipe_cache", no_argument, NULL, 'c' },
{ "show_text", no_argument, NULL, 't' },
{ "just_exit", no_argument, NULL, 'x' },
{ "locale", required_argument, NULL, 'l' },
{ NULL, 0, NULL, 0 },
};

事实上，各个厂商可以根据需求而进行扩展，只要recovery和上层应用保持一致即可。——在Recovery模式下的文本显示一文中讲到了locale的注意事项，如前面Java代码给出的，传入的是Locale.toString()，而不是Locale.getLanguage()。

BCB (Bootloader Control Block)

待补充

接下来分析应用层如何进入recovery模式的，包括ShutdownThread.java、android_reboot.c等的分析。