1/*
2 * Copyright 2016 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
17package [email protected];
18
19/**
20 * The Boot Control HAL is designed to allow for managing sets of redundant
21 * partitions, called slots, that can be booted from independently. Slots
22 * are sets of partitions whose names differ only by a given suffix.
23 * They are identified here by a 0 indexed number and associated with their
24 * suffix, which is appended to the base name for any particular partition
25 * to find the one associated with that slot.
26 * The primary use of this set up is to allow for background updates while
27 * the device is running, and to provide a fallback in the event that the
28 * update fails.
29 */
30interface IBootControl {
31  /**
32   * getNumberSlots() returns the number of available slots.
33   * For instance, a system with a single set of partitions must return
34   * 1, a system with A/B must return 2, A/B/C -> 3 and so on. A system with
35   * less than two slots doesn't support background updates, for example if
36   * running from a virtual machine with only one copy of each partition for the
37   * purpose of testing.
38   */
39  getNumberSlots() generates (uint32_t numSlots);
40
41  /**
42   * getCurrentSlot() returns the slot number of that the current boot is booted
43   * from, for example slot number 0 (Slot A). It is assumed that if the current
44   * slot is A, then the block devices underlying B can be accessed directly
45   * without any risk of corruption.
46   * The returned value is always guaranteed to be strictly less than the
47   * value returned by getNumberSlots. Slots start at 0 and finish at
48   * getNumberSlots() - 1. The value returned here must match the suffix passed
49   * from the bootloader, regardless of which slot is active or successful.
50   */
51  getCurrentSlot() generates (Slot slot);
52
53  /**
54   * markBootSuccessful() marks the current slot as having booted successfully.
55   *
56   * Returns whether the command succeeded.
57   */
58  markBootSuccessful() generates (CommandResult error);
59
60  /**
61   * setActiveBootSlot() marks the slot passed in parameter as the active boot
62   * slot (see getCurrentSlot for an explanation of the "slot" parameter). This
63   * overrides any previous call to setSlotAsUnbootable.
64   * Returns whether the command succeeded.
65   */
66  setActiveBootSlot(Slot slot) generates (CommandResult error);
67
68  /**
69   * setSlotAsUnbootable() marks the slot passed in parameter as
70   * an unbootable. This can be used while updating the contents of the slot's
71   * partitions, so that the system must not attempt to boot a known bad set up.
72   * Returns whether the command succeeded.
73   */
74  setSlotAsUnbootable(Slot slot) generates (CommandResult error);
75
76  /**
77   * isSlotBootable() returns if the slot passed in parameter is bootable. Note
78   * that slots can be made unbootable by both the bootloader and by the OS
79   * using setSlotAsUnbootable.
80   * Returns TRUE if the slot is bootable, FALSE if it's not, and INVALID_SLOT
81   * if slot does not exist.
82   */
83  isSlotBootable(Slot slot) generates (BoolResult bootable);
84
85  /**
86   * isSlotMarkedSucessful() returns if the slot passed in parameter has been
87   * marked as successful using markBootSuccessful. Note that only the current
88   * slot can be marked as successful but any slot can be queried.
89   * Returns TRUE if the slot has been marked as successful, FALSE if it has
90   * not, and INVALID_SLOT if the slot does not exist.
91   */
92  isSlotMarkedSuccessful(Slot slot) generates (BoolResult successful);
93
94  /**
95   * getSuffix() returns the string suffix used by partitions that correspond to
96   * the slot number passed in as a parameter. The bootloader must pass the
97   * suffix of the currently active slot either through a kernel command line
98   * property at androidboot.slot_suffix, or the device tree at
99   * /firmware/android/slot_suffix.
100   * Returns the empty string "" if slot does not match an existing slot.
101   */
102  getSuffix(Slot slot) generates (string slotSuffix);
103};
104
105