Merge "health filesystem: update garbageCollect() function."

am: e1ca153525

Change-Id: I11cc775092927e93a75db411bd47035d14598d14

health/filesystem/1.0/Android.bp

@@ -9,6 +9,7 @@ hidl_interface {
     srcs: [
         "types.hal",
         "IFileSystem.hal",
+        "IGarbageCollectCallback.hal",
     ],
     interfaces: [
         "android.hidl.base@1.0",

health/filesystem/1.0/IFileSystem.hal

@@ -16,18 +16,34 @@
 
 package android.hardware.health.filesystem@1.0;
 
+import IGarbageCollectCallback;
+
 /**
  * IFileSystem is an interface that provides operations on underlying storage
  * devices, including flash memory.
  */
 interface IFileSystem {
     /**
-     * Start garbage collection on the driver of storage devices. This function
-     * must be called at regular intervals when it is a good time for a
-     * longer-running cleanup tasks.
+     * Start garbage collection on the driver of storage devices.
+     *
+     * Garbage collection must be started at regular intervals when it is a good
+     * time for a longer-running cleanup tasks, roughly daily.
+     *
+     * When garbage collection finishes or encounters an error before the
+     * specified timeout, the implementation must call IGarbageCollect.finish
+     * immediately with appropriate result.
+     *
+     * If garbage collection does not finish within the specified timeout,
+     * the implementation must stop garbage collection, and must not call
+     * IGarbageCollect.finish.
+     *
+     * @param timeoutSeconds timeout in seconds. The implementation must
+     *     return after the timeout is reached.
+     *
+     * @param callback callback interface. Callback must be null if the client
+     *     does not need to receive any callbacks.
      *
-     * @return result Execution result. See documentation for Result for
-     *     details.
      */
-    garbageCollect() generates (Result result);
+    oneway garbageCollect(uint64_t timeoutSeconds,
+                          IGarbageCollectCallback callback);
 };

health/filesystem/1.0/IGarbageCollectCallback.hal

@@ -0,0 +1,30 @@
+/*
+ * Copyright (C) 2018 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package android.hardware.health.filesystem@1.0;
+
+/**
+ * Callback interface to IFileSystem.garbageCollect.
+ */
+interface IGarbageCollectCallback {
+    /**
+     * When garbage collection has finished, the implementation must
+     * invoke this function to indicate the result of the garbage collection.
+     *
+     * @return result Execution result. See documentation for Result for
+     *     details.
+     */
+    oneway onFinish(Result result);
+};

health/filesystem/1.0/types.hal

@@ -24,10 +24,6 @@ enum Result : uint32_t {
      * Execution of the method is successful.
      */
     SUCCESS = 0,
-    /**
-     * Execution of the method timed out.
-     */
-    TIMEOUT,
     /**
      * An IO error is encountered when the HAL communicates with the device.
      */