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 ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H 18 #define ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H 19 20 #include <hardware/hardware.h> 21 22 __BEGIN_DECLS 23 24 #define BOOT_CONTROL_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 25 26 /** 27 * The id of this module 28 */ 29 #define BOOT_CONTROL_HARDWARE_MODULE_ID "bootctrl" 30 31 /* 32 * The Boot Control HAL is designed to allow for managing sets of redundant 33 * partitions, called slots, that can be booted from independantly. Slots 34 * are sets of partitions whose names differ only by a given suffix. 35 * They are identified here by a 0 indexed number, and associated with their 36 * suffix, which can be appended to the base name for any particular partition 37 * to find the one associated with that slot. The bootloader must pass the suffix 38 * of the currently active slot either through a kernel command line property at 39 * androidboot.slot_suffix, or the device tree at /firmware/android/slot_suffix. 40 * The primary use of this set up is to allow for background updates while the 41 * device is running, and to provide a fallback in the event that the update fails. 42 */ 43 44 45 /** 46 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 47 * and the fields of this data structure must begin with hw_module_t 48 * followed by module specific information. 49 */ 50 typedef struct boot_control_module { 51 struct hw_module_t common; 52 53 /* 54 * (*init)() perform any initialization tasks needed for the HAL. 55 * This is called only once. 56 */ 57 void (*init)(struct boot_control_module *module); 58 59 /* 60 * (*getNumberSlots)() returns the number of available slots. 61 * For instance, a system with a single set of partitions would return 62 * 1, a system with A/B would return 2, A/B/C -> 3... 63 */ 64 unsigned (*getNumberSlots)(struct boot_control_module *module); 65 66 /* 67 * (*getCurrentSlot)() returns the value letting the system know 68 * whether the current slot is A or B. The meaning of A and B is 69 * left up to the implementer. It is assumed that if the current slot 70 * is A, then the block devices underlying B can be accessed directly 71 * without any risk of corruption. 72 * The returned value is always guaranteed to be strictly less than the 73 * value returned by getNumberSlots. Slots start at 0 and 74 * finish at getNumberSlots() - 1 75 */ 76 unsigned (*getCurrentSlot)(struct boot_control_module *module); 77 78 /* 79 * (*markBootSuccessful)() marks the current slot 80 * as having booted successfully 81 * 82 * Returns 0 on success, -errno on error. 83 */ 84 int (*markBootSuccessful)(struct boot_control_module *module); 85 86 /* 87 * (*setActiveBootSlot)() marks the slot passed in parameter as 88 * the active boot slot (see getCurrentSlot for an explanation 89 * of the "slot" parameter). This overrides any previous call to 90 * setSlotAsUnbootable. 91 * Returns 0 on success, -errno on error. 92 */ 93 int (*setActiveBootSlot)(struct boot_control_module *module, unsigned slot); 94 95 /* 96 * (*setSlotAsUnbootable)() marks the slot passed in parameter as 97 * an unbootable. This can be used while updating the contents of the slot's 98 * partitions, so that the system will not attempt to boot a known bad set up. 99 * Returns 0 on success, -errno on error. 100 */ 101 int (*setSlotAsUnbootable)(struct boot_control_module *module, unsigned slot); 102 103 /* 104 * (*isSlotBootable)() returns if the slot passed in parameter is 105 * bootable. Note that slots can be made unbootable by both the 106 * bootloader and by the OS using setSlotAsUnbootable. 107 * Returns 1 if the slot is bootable, 0 if it's not, and -errno on 108 * error. 109 */ 110 int (*isSlotBootable)(struct boot_control_module *module, unsigned slot); 111 112 /* 113 * (*getSuffix)() returns the string suffix used by partitions that 114 * correspond to the slot number passed in parameter. The returned string 115 * is expected to be statically allocated and not need to be freed. 116 * Returns NULL if slot does not match an existing slot. 117 */ 118 const char* (*getSuffix)(struct boot_control_module *module, unsigned slot); 119 120 /* 121 * (*isSlotMarkedSucessful)() returns if the slot passed in parameter has 122 * been marked as successful using markBootSuccessful. 123 * Returns 1 if the slot has been marked as successful, 0 if it's 124 * not the case, and -errno on error. 125 */ 126 int (*isSlotMarkedSuccessful)(struct boot_control_module *module, unsigned slot); 127 128 void* reserved[31]; 129 } boot_control_module_t; 130 131 132 __END_DECLS 133 134 #endif // ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H 135