camera2: Update HAL docs on eviction behavior.

Bug: 19186859
Change-Id: Ie051f966a758c68d354250c245a87df57a4f4ae3

1 files changed, 115 insertions, 10 deletions

diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index fa22c47..c2d4536 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -236,10 +236,12 @@ typedef struct camera_info {
     const camera_metadata_t *static_camera_characteristics;
 
     /**
-     * The total resource "cost" of using this this camera, represented as
-     * an integer value in the range [0, 100] where 100 represents total usage
-     * of the shared resource that is the limiting bottleneck of the camera
-     * subsystem.
+     * The total resource "cost" of using this camera, represented as an integer
+     * value in the range [0, 100] where 100 represents total usage of the shared
+     * resource that is the limiting bottleneck of the camera subsystem.  This may
+     * be a very rough estimate, and is used as a hint to the camera service to
+     * determine when to disallow multiple applications from simultaneously
+     * opening different cameras advertised by the camera service.
      *
      * The camera service must be able to simultaneously open and use any
      * combination of camera devices exposed by the HAL where the sum of
@@ -249,12 +251,112 @@ typedef struct camera_info {
      * available in the configuration settings exposed for that device through
      * the camera metadata.
      *
-     * Note: The camera service may still attempt to simultaneously open
-     * combinations of camera devices with a total resource cost > 100.  This
-     * may succeed or fail.  If this succeeds, combinations of configurations
-     * that are not supported should fail during the configure calls.  If the
-     * total resource cost is <= 100, configuration should never fail due to
-     * resource constraints.
+     * The camera service may still attempt to simultaneously open combinations
+     * of camera devices with a total resource cost > 100.  This may succeed or
+     * fail.  If this succeeds, combinations of configurations that are not
+     * supported due to resource constraints from having multiple open devices
+     * should fail during the configure calls.  If the total resource cost is
+     * <= 100, open and configure should never fail for any stream configuration
+     * settings or other device capabilities that would normally succeed for a
+     * device when it is the only open camera device.
+     *
+     * This field will be used to determine whether background applications are
+     * allowed to use this camera device while other applications are using other
+     * camera devices.  Note: multiple applications will never be allowed by the
+     * camera service to simultaneously open the same camera device.
+     *
+     * Example use cases:
+     *
+     * Ex. 1: Camera Device 0 = Back Camera
+     *        Camera Device 1 = Front Camera
+     *   - Using both camera devices causes a large framerate slowdown due to
+     *     limited ISP bandwidth.
+     *
+     *   Configuration:
+     *
+     *   Camera Device 0 - resource_cost = 51
+     *                     conflicting_devices = null
+     *   Camera Device 1 - resource_cost = 51
+     *                     conflicting_devices = null
+     *
+     *   Result:
+     *
+     *   Since the sum of the resource costs is > 100, if a higher-priority
+     *   application has either device open, no lower-priority applications will be
+     *   allowed by the camera service to open either device.  If a lower-priority
+     *   application is using a device that a higher-priority subsequently attempts
+     *   to open, the lower-priority application will be forced to disconnect the
+     *   the device.
+     *
+     *   If the highest-priority application chooses, it may still attempt to open
+     *   both devices (since these devices are not listed as conflicting in the
+     *   conflicting_devices fields), but usage of these devices may fail in the
+     *   open or configure calls.
+     *
+     * Ex. 2: Camera Device 0 = Left Back Camera
+     *        Camera Device 1 = Right Back Camera
+     *        Camera Device 2 = Combined stereo camera using both right and left
+     *                          back camera sensors used by devices 0, and 1
+     *        Camera Device 3 = Front Camera
+     *   - Due to do hardware constraints, up to two cameras may be open at once. The
+     *     combined stereo camera may never be used at the same time as either of the
+     *     two back camera devices (device 0, 1), and typically requires too much
+     *     bandwidth to use at the same time as the front camera (device 3).
+     *
+     *   Configuration:
+     *
+     *   Camera Device 0 - resource_cost = 50
+     *                     conflicting_devices = { 2 }
+     *   Camera Device 1 - resource_cost = 50
+     *                     conflicting_devices = { 2 }
+     *   Camera Device 2 - resource_cost = 100
+     *                     conflicting_devices = { 0, 1 }
+     *   Camera Device 3 - resource_cost = 50
+     *                     conflicting_devices = null
+     *
+     *   Result:
+     *
+     *   Based on the conflicting_devices fields, the camera service guarantees that
+     *   the following sets of open devices will never be allowed: { 1, 2 }, { 0, 2 }.
+     *
+     *   Based on the resource_cost fields, if a high-priority foreground application
+     *   is using camera device 0, a background application would be allowed to open
+     *   camera device 1 or 3 (but would be forced to disconnect it again if the
+     *   foreground application opened another device).
+     *
+     *   The highest priority application may still attempt to simultaneously open
+     *   devices 0, 2, and 3, but the HAL may fail in open or configure calls for
+     *   this combination.
+     *
+     * Ex. 3: Camera Device 0 = Back Camera
+     *        Camera Device 1 = Front Camera
+     *        Camera Device 2 = Low-power Front Camera that uses the same
+     *                          sensor as device 1, but only exposes image stream
+     *                          resolutions that can be used in low-power mode
+     *  - Using both front cameras (device 1, 2) at the same time is impossible due
+     *    a shared physical sensor.  Using the back and "high-power" front camera
+     *    (device 1) may be impossible for some stream configurations due to hardware
+     *    limitations, but the "low-power" front camera option may always be used as
+     *    it has special dedicated hardware.
+     *
+     *   Configuration:
+     *
+     *   Camera Device 0 - resource_cost = 100
+     *                     conflicting_devices = null
+     *   Camera Device 1 - resource_cost = 100
+     *                     conflicting_devices = { 2 }
+     *   Camera Device 2 - resource_cost = 0
+     *                     conflicting_devices = { 1 }
+     *   Result:
+     *
+     *   Based on the conflicting_devices fields, the camera service guarantees that
+     *   the following sets of open devices will never be allowed: { 1, 2 }.
+     *
+     *   Based on the resource_cost fields, only the highest priority application
+     *   may attempt to open both device 0 and 1 at the same time. If a higher-priority
+     *   application is not using device 1 or 2, a low-priority background application
+     *   may open device 2 (but will be forced to disconnect it if a higher-priority
+     *   application subsequently opens device 1 or 2).
      *
      * Version information (based on camera_module_t.common.module_api_version):
      *
@@ -281,6 +383,9 @@ typedef struct camera_info {
      * The camera service will never simultaneously open any of the devices
      * in this list while this camera device is open.
      *
+     * The strings pointed to in this field will not be cleaned up by the camera
+     * service, and must remain while this device is plugged in.
+     *
      * Version information (based on camera_module_t.common.module_api_version):
      *
      *  CAMERA_MODULE_API_VERSION_2_3 or lower: