1 /*
2  * Copyright (C) 2019 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 package android.gsi;
18 
19 import android.gsi.AvbPublicKey;
20 import android.gsi.GsiProgress;
21 import android.gsi.IGsiServiceCallback;
22 import android.gsi.IImageService;
23 import android.os.ParcelFileDescriptor;
24 
25 /** {@hide} */
26 interface IGsiService {
27     /* Status codes for GsiProgress.status */
28     const int STATUS_NO_OPERATION = 0;
29     const int STATUS_WORKING = 1;
30     const int STATUS_COMPLETE = 2;
31 
32     /* Install succeeded. */
33     const int INSTALL_OK = 0;
34     /* Install failed with a generic system error. */
35     const int INSTALL_ERROR_GENERIC = 1;
36     /* Install failed because there was no free space. */
37     const int INSTALL_ERROR_NO_SPACE = 2;
38     /**
39      * Install failed because the file system was too fragmented or did not
40      * have enough additional free space.
41      */
42     const int INSTALL_ERROR_FILE_SYSTEM_CLUTTERED = 3;
43 
44     /**
45      * Write bytes from a stream to the on-disk GSI.
46      *
47      * @param stream        Stream descriptor.
48      * @param bytes         Number of bytes that can be read from stream.
49      * @return              true on success, false otherwise.
50      */
commitGsiChunkFromStream(in ParcelFileDescriptor stream, long bytes)51     boolean commitGsiChunkFromStream(in ParcelFileDescriptor stream, long bytes);
52 
53     /**
54      * Query the progress of the current asynchronous install operation. This
55      * can be called while another operation is in progress.
56      */
getInstallProgress()57     GsiProgress getInstallProgress();
58 
59     /**
60      * Set the file descriptor that points to a ashmem which will be used
61      * to fetch data during the commitGsiChunkFromAshmem.
62      *
63      * @param stream        fd that points to a ashmem
64      * @param size          size of the ashmem file
65      */
setGsiAshmem(in ParcelFileDescriptor stream, long size)66     boolean setGsiAshmem(in ParcelFileDescriptor stream, long size);
67 
68     /**
69      * Write bytes from ashmem previously set with setGsiAshmem to GSI partition
70      *
71      * @param bytes         Number of bytes to submit
72      * @return              true on success, false otherwise.
73      */
commitGsiChunkFromAshmem(long bytes)74     boolean commitGsiChunkFromAshmem(long bytes);
75 
76     /**
77      * Complete a GSI installation and mark it as bootable. The caller is
78      * responsible for rebooting the device as soon as possible.
79      *
80      * @param oneShot       If true, the GSI will boot once and then disable itself.
81      *                      It can still be re-enabled again later with setGsiBootable.
82      * @param dsuSlot       The DSU slot to be enabled. Possible values are available
83      *                      with the getInstalledDsuSlots()
84      *
85      * @return              INSTALL_* error code.
86      */
enableGsi(boolean oneShot, @utf8InCpp String dsuSlot)87     int enableGsi(boolean oneShot, @utf8InCpp String dsuSlot);
88 
89     /**
90      * Asynchronous enableGsi
91      * @param result        callback for result
92      */
93     @SuppressWarnings(value={"mixed-oneway"})
enableGsiAsync(boolean oneShot, @utf8InCpp String dsuSlot, IGsiServiceCallback result)94     oneway void enableGsiAsync(boolean oneShot, @utf8InCpp String dsuSlot, IGsiServiceCallback result);
95 
96     /**
97      * @return              True if Gsi is enabled
98      */
isGsiEnabled()99     boolean isGsiEnabled();
100 
101     /**
102      * Cancel an in-progress GSI install.
103      */
cancelGsiInstall()104     boolean cancelGsiInstall();
105 
106     /**
107      * Return if a GSI installation is currently in-progress.
108      */
isGsiInstallInProgress()109     boolean isGsiInstallInProgress();
110 
111     /**
112      * Remove a GSI install. This will completely remove and reclaim space used
113      * by the GSI and its userdata. If currently running a GSI, space will be
114      * reclaimed on the reboot.
115      *
116      * @return              true on success, false otherwise.
117      */
removeGsi()118     boolean removeGsi();
119 
120     /**
121      * Asynchronous removeGsi
122      * @param result        callback for result
123      */
124     @SuppressWarnings(value={"mixed-oneway"})
removeGsiAsync(IGsiServiceCallback result)125     oneway void removeGsiAsync(IGsiServiceCallback result);
126 
127     /**
128      * Disables a GSI install. The image and userdata will be retained, but can
129      * be re-enabled at any time with setGsiBootable.
130      */
disableGsi()131     boolean disableGsi();
132 
133     /**
134      * Returns true if a gsi is installed.
135      */
isGsiInstalled()136     boolean isGsiInstalled();
137     /**
138      * Returns true if the gsi is currently running, false otherwise.
139      */
isGsiRunning()140     boolean isGsiRunning();
141 
142     /**
143      * Returns the active DSU slot if there is any DSU installed, empty string otherwise.
144      */
getActiveDsuSlot()145     @utf8InCpp String getActiveDsuSlot();
146 
147     /**
148      * If a GSI is installed, returns the directory where the installed images
149      * are located. Otherwise, returns an empty string.
150      */
getInstalledGsiImageDir()151     @utf8InCpp String getInstalledGsiImageDir();
152 
153     /**
154      * Returns all installed DSU slots.
155      */
getInstalledDsuSlots()156     @utf8InCpp List<String> getInstalledDsuSlots();
157 
158     /**
159      * Open a DSU installation
160      *
161      * @param installDir The directory to install DSU images under. This must be
162      *     either an empty string (which will use the default /data/gsi),
163      *     "/data/gsi", or a mount under /mnt/media_rw. It may end in a trailing slash.
164      *
165      * @return              0 on success, an error code on failure.
166      */
openInstall(in @tf8InCpp String installDir)167     int openInstall(in @utf8InCpp String installDir);
168 
169     /**
170      * Close a DSU installation. An installation is complete after the close been invoked.
171      */
closeInstall()172     int closeInstall();
173 
174     /**
175      * Create a DSU partition within the current installation
176      *
177      * @param name The DSU partition name
178      * @param size Bytes in the partition
179      * @param readOnly True if the partition is readOnly when DSU is running
180      */
createPartition(in @tf8InCpp String name, long size, boolean readOnly)181     int createPartition(in @utf8InCpp String name, long size, boolean readOnly);
182 
183     /**
184      * Complete the current partition installation. A partition installation is
185      * complete after all pending bytes are written successfully.
186      * Returns an error if current installation still have pending bytes.
187      * Returns an error if there is any internal filesystem error.
188      *
189      * @return              0 on success, an error code on failure.
190      */
closePartition()191     int closePartition();
192 
193     /**
194      * Wipe a partition. This will not work if the GSI is currently running.
195      * The partition will not be removed, but the first block will be zeroed.
196      *
197      * @param name The DSU partition name
198      *
199      * @return              0 on success, an error code on failure.
200      */
zeroPartition(in @tf8InCpp String name)201     int zeroPartition(in @utf8InCpp String name);
202 
203     /**
204      * Open a handle to an IImageService for the given metadata and data storage paths.
205      *
206      * @param prefix        A prefix used to organize images. The data path will become
207      *                      /data/gsi/{prefix} and the metadata path will become
208      *                      /metadata/gsi/{prefix}.
209      */
openImageService(@tf8InCpp String prefix)210     IImageService openImageService(@utf8InCpp String prefix);
211 
212     /**
213      * Dump diagnostic information about device-mapper devices. This is intended
214      * for dumpstate.
215      */
dumpDeviceMapperDevices()216     @utf8InCpp String dumpDeviceMapperDevices();
217 
218     /**
219      * Retrieve AVB public key from the current mapped partition.
220      * This works only while partition device is mapped and the end-of-partition
221      * AVB footer has been written.
222      * A call to createPartition() does the following things:
223      * 1. Close the previous partition installer, thus unmap the partition.
224      * 2. Open a new partition installer.
225      * 3. Create and map the new partition.
226      *
227      * In other words, getAvbPublicKey() should be called after
228      * createPartition() is called and before closePartition() is called.
229      *
230      * @param dst           Output the AVB public key.
231      * @return              0 on success, an error code on failure.
232      */
getAvbPublicKey(out AvbPublicKey dst)233     int getAvbPublicKey(out AvbPublicKey dst);
234 
235     /**
236      * Returns the suggested scratch partition size for overlayFS.
237      */
suggestScratchSize()238     long suggestScratchSize();
239 }
240