camera2: Update HAL docs on eviction behavior.
Bug: 19186859
Change-Id: Ie051f966a758c68d354250c245a87df57a4f4ae3
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 @@
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 @@
* 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 @@
* 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: