camera.provider: Add @2.5 to support notifyDeviceStatusChange

Sometimes, the camera service needs to notify a camera HAL that the
overall device physical state has changed, so that the HAL can
properly remap how it handles logical multicamera devices or similar.

Test: Builds, new VTS tests pass
Bug: 121379978
Change-Id: I0982fdecaf53a0529289d63c08c5a31264ee7ec7

camera/provider/2.5/Android.bp

@@ -0,0 +1,25 @@
+// This file is autogenerated by hidl-gen -Landroidbp.
+
+hidl_interface {
+    name: "android.hardware.camera.provider@2.5",
+    root: "android.hardware",
+    vndk: {
+        enabled: true,
+    },
+    srcs: [
+        "types.hal",
+        "ICameraProvider.hal",
+    ],
+    interfaces: [
+        "android.hardware.camera.common@1.0",
+        "android.hardware.camera.device@1.0",
+        "android.hardware.camera.device@3.2",
+        "android.hardware.camera.provider@2.4",
+        "android.hidl.base@1.0",
+    ],
+    types: [
+        "DeviceState",
+    ],
+    gen_java: false,
+}
+

camera/provider/2.5/ICameraProvider.hal

@@ -0,0 +1,68 @@
+/*
+ * 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.camera.provider@2.5;
+
+import android.hardware.camera.common@1.0::Status;
+import android.hardware.camera.provider@2.4::ICameraProvider;
+
+/**
+ * Camera provider HAL
+ *
+ * Version 2.5 adds support for the notifyDeviceStateChange method
+ */
+interface ICameraProvider extends @2.4::ICameraProvider {
+
+    /**
+     * notifyDeviceStateChange:
+     *
+     * Notify the HAL provider that the state of the overall device has
+     * changed in some way that the HAL may want to know about.
+     *
+     * For example, a physical shutter may have been uncovered or covered,
+     * or a camera may have been covered or uncovered by an add-on keyboard
+     * or other accessory.
+     *
+     * The state is a bitfield of potential states, and some physical configurations
+     * could plausibly correspond to multiple different combinations of state bits.
+     * The HAL must ignore any state bits it is not actively using to determine
+     * the appropriate camera configuration.
+     *
+     * For example, on some devices the FOLDED state could mean that
+     * backward-facing cameras are covered by the fold, so FOLDED by itself implies
+     * BACK_COVERED. But other devices may support folding but not cover any cameras
+     * when folded, so for those FOLDED would not imply any of the other flags.
+     * Since these relationships are very device-specific, it is difficult to specify
+     * a comprehensive policy.  But as a recommendation, it is suggested that if a flag
+     * necessarily implies other flags are set as well, then those flags should be set.
+     * So even though FOLDED would be enough to infer BACK_COVERED on some devices, the
+     * BACK_COVERED flag should also be set for clarity.
+     *
+     * This method may be invoked by the HAL client at any time. It must not
+     * cause any active camera device sessions to be closed, but may dynamically
+     * change which physical camera a logical multi-camera is using for its
+     * active and future output.
+     *
+     * The method must be invoked by the HAL client at least once before the
+     * client calls ICameraDevice::open on any camera device interfaces listed
+     * by this provider, to establish the initial device state.
+     *
+     * @param newState
+     *    The new state of the device.
+     */
+    notifyDeviceStateChange(bitfield<DeviceState> newState);
+
+};

camera/provider/2.5/types.hal

@@ -0,0 +1,52 @@
+/*
+ * 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.camera.provider@2.5;
+
+/**
+ * DeviceState:
+ *
+ * Possible physical states of the overall device, for use with
+ * ICameraProvider::notifyDeviceStateChange.
+ *
+ */
+enum DeviceState : uint64_t {
+    /**
+     * The device is in its normal physical configuration. This is the default if the
+     * device does not support multiple different states.
+     */
+    NORMAL = 0,
+
+    /**
+     * Camera device(s) facing backward are covered.
+     */
+    BACK_COVERED = 1 << 0,
+
+    /**
+     * Camera device(s) facing foward are covered.
+     */
+    FRONT_COVERED = 1 << 1,
+
+    /**
+     * The device is folded.  If not set, the device is unfolded or does not
+     * support folding.
+     *
+     * The exact point when this status change happens during the folding
+     * operation is device-specific.
+     */
+    FOLDED = 1 << 2,
+
+};

compatibility_matrices/compatibility_matrix.current.xml

@@ -113,7 +113,7 @@
     </hal>
     <hal format="hidl" optional="true">
         <name>android.hardware.camera.provider</name>
-        <version>2.4</version>
+        <version>2.5</version>
         <interface>
             <name>ICameraProvider</name>
             <regex-instance>[^/]+/[0-9]+</regex-instance>