Camera: add OFFLINE_PROCESSING APIs
Also a typo fix in metadata doc.
Test: N/A. New API skeleton, no implementation yet.
Bug: 135142453
Change-Id: I4852ee28242afabe81b02cfef39994c5d2705359
diff --git a/camera/device/3.6/Android.bp b/camera/device/3.6/Android.bp
new file mode 100644
index 0000000..8766b93
--- /dev/null
+++ b/camera/device/3.6/Android.bp
@@ -0,0 +1,24 @@
+// This file is autogenerated by hidl-gen -Landroidbp.
+
+hidl_interface {
+ name: "android.hardware.camera.device@3.6",
+ root: "android.hardware",
+ vndk: {
+ enabled: true,
+ },
+ srcs: [
+ "types.hal",
+ "ICameraDeviceSession.hal",
+ "ICameraOfflineSession.hal",
+ ],
+ interfaces: [
+ "android.hardware.camera.common@1.0",
+ "android.hardware.camera.device@3.2",
+ "android.hardware.camera.device@3.3",
+ "android.hardware.camera.device@3.4",
+ "android.hardware.camera.device@3.5",
+ "android.hardware.graphics.common@1.0",
+ "android.hidl.base@1.0",
+ ],
+ gen_java: false,
+}
diff --git a/camera/device/3.6/ICameraDeviceSession.hal b/camera/device/3.6/ICameraDeviceSession.hal
new file mode 100644
index 0000000..00ebcc3
--- /dev/null
+++ b/camera/device/3.6/ICameraDeviceSession.hal
@@ -0,0 +1,132 @@
+/*
+ * Copyright (C) 2019 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.device@3.6;
+
+import android.hardware.camera.common@1.0::Status;
+import @3.5::ICameraDeviceSession;
+import @3.5::StreamConfiguration;
+import ICameraOfflineSession;
+
+/**
+ * Camera device active session interface.
+ *
+ * Obtained via ICameraDevice::open(), this interface contains the methods to
+ * configure and request captures from an active camera device.
+ */
+interface ICameraDeviceSession extends @3.5::ICameraDeviceSession {
+ /**
+ * configureStreams_3_6:
+ *
+ * Identical to @3.5::ICameraDeviceSession.configureStreams, except that:
+ *
+ * - a boolean supportOffline is added to HalStreamConfiguration to indicate
+ * if this stream can be switched to offline mode later.
+ *
+ * @return status Status code for the operation, one of:
+ * OK:
+ * On successful stream configuration.
+ * INTERNAL_ERROR:
+ * If there has been a fatal error and the device is no longer
+ * operational. Only close() can be called successfully by the
+ * framework after this error is returned.
+ * ILLEGAL_ARGUMENT:
+ * If the requested stream configuration is invalid. Some examples
+ * of invalid stream configurations include:
+ * - Including more than 1 INPUT stream
+ * - Not including any OUTPUT streams
+ * - Including streams with unsupported formats, or an unsupported
+ * size for that format.
+ * - Including too many output streams of a certain format.
+ * - Unsupported rotation configuration
+ * - Stream sizes/formats don't satisfy the
+ * StreamConfigurationMode requirements
+ * for non-NORMAL mode, or the requested operation_mode is not
+ * supported by the HAL.
+ * - Unsupported usage flag
+ * The camera service cannot filter out all possible illegal stream
+ * configurations, since some devices may support more simultaneous
+ * streams or larger stream resolutions than the minimum required
+ * for a given camera device hardware level. The HAL must return an
+ * ILLEGAL_ARGUMENT for any unsupported stream set, and then be
+ * ready to accept a future valid stream configuration in a later
+ * configureStreams call.
+ * @return halConfiguration The stream parameters desired by the HAL for
+ * each stream, including maximum buffers, the usage flags, and the
+ * override format.
+ */
+ configureStreams_3_6(@3.5::StreamConfiguration requestedConfiguration)
+ generates (Status status, HalStreamConfiguration halConfiguration);
+
+ /**
+ * switchToOffline:
+ *
+ * Switch the current running session from actively streaming mode to the
+ * offline mode. See ICameraOfflineSession for more details.
+ *
+ * The streamsToKeep argument contains list of streams IDs where application
+ * still needs its output. For all streams application does not need anymore,
+ * camera HAL can send ERROR_BUFFER to speed up the transition, or even send
+ * ERROR_REQUEST if all output targets of a request is not needed. By the
+ * time this call returns, camera HAL must have returned all buffers coming
+ * from streams no longer needed and have erased buffer caches of such streams.
+ *
+ * For all requests that are going to be transferred to offline session,
+ * the ICameraDeviceSession is responsible to capture all input buffers from
+ * the image sensor before the switchToOffline call returns. Before
+ * switchToOffline returns, camera HAL must have completed all requests not
+ * switching to offline mode, and collected information on what streams and
+ * requests are going to continue in the offline session, in the
+ * offlineSessionInfo output argument.
+ *
+ * If there are no requests qualified to be transferred to offline session,
+ * the camera HAL must return a null ICameraOfflineSession object with OK
+ * status. In this scenario, the camera HAL still must flush all inflight
+ * requests and unconfigure all streams before returning this call.
+ *
+ * After switchToOffline returns, the ICameraDeviceSession must be back to
+ * unconfigured state as if it is just created and no streams are configured.
+ * Also, camera HAL must not call any methods in ICameraDeviceCallback since
+ * all unfinished requests are now transferred to the offline session.
+ * After the call returns, camera service may then call close to close
+ * the camera device, or call configureStream* again to reconfigure the
+ * camera and then send new capture requests with processCaptureRequest. In
+ * the latter case, it is legitimate for camera HAL to call methods in
+ * ICameraDeviceCallback again in response to the newly submitted capture
+ * requests.
+ *
+ * @return status Status code for the operation, one of:
+ * OK:
+ * On switching to offline session and unconfiguring streams
+ * successfully.
+ * ILLEGAL_ARGUMENT:
+ * If camera does not support offline mode in any one of streams
+ * in streamsToKeep argument. Note that the camera HAL must report
+ * if a stream supports offline mode in HalStreamConfiguration
+ * output of configureStreams_3_6 method. If all streams in
+ * streamsToKeep argument support offline mode, then the camera HAL
+ * must not return this error.
+ *
+ *
+ * @return offlineSessionInfo Information on what streams and requests will
+ * be transferred to offline session to continue processing.
+ *
+ * @return offlineSession The offline session object camera service will use
+ * to interact with.
+ */
+ switchToOffline(vec<int32_t> streamsToKeep) generates (Status status,
+ CameraOfflineSessionInfo offlineSessionInfo, ICameraOfflineSession offlineSession);
+};
diff --git a/camera/device/3.6/ICameraOfflineSession.hal b/camera/device/3.6/ICameraOfflineSession.hal
new file mode 100644
index 0000000..03cea64
--- /dev/null
+++ b/camera/device/3.6/ICameraOfflineSession.hal
@@ -0,0 +1,80 @@
+/*
+ * Copyright (C) 2019 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.device@3.6;
+
+import @3.5::ICameraDeviceCallback;
+
+/**
+ * Camera device offline session interface.
+ *
+ * Obtained via ICameraDeviceSession::switchToOffline(), this interface contains
+ * the methods and callback interfaces that define how camera service interacts
+ * with an offline session.
+ *
+ * An offline session contains some unfinished capture requests that were submitted
+ * to the parent ICameraDeviceSession before calling switchToOffline, and is
+ * responsible for delivering these capture results back to camera service regardless
+ * of whether the parent camera device is still opened or not. An offline session must
+ * not have access to the camera device's image sensor. During switchToOffline
+ * call, camera HAL must capture all necessary frames from the image sensor that
+ * is needed for completing the requests offline later.
+ */
+interface ICameraOfflineSession {
+ /**
+ * Set the callbacks for offline session to communicate with camera service.
+ *
+ * Offline session is responsible to store all callbacks the camera HAL
+ * generated after the return of ICameraDeviceSession::switchToOffline, and
+ * send them to camera service once this method is called.
+ *
+ * Camera service must not call this method more than once, so these
+ * callbacks can be assumed to be constant after the first setCallback call.
+ */
+ setCallback(ICameraDeviceCallback cb);
+
+ /**
+ * getCaptureResultMetadataQueue:
+ *
+ * Retrieves the queue used along with
+ * ICameraDeviceCallback#processCaptureResult.
+ *
+ * Clients to ICameraOfflineSession must:
+ * - Call getCaptureRequestMetadataQueue to retrieve the fast message queue;
+ * - In implementation of ICameraDeviceCallback, test whether
+ * .fmqResultSize field is zero.
+ * - If .fmqResultSize != 0, read result metadata from the fast message
+ * queue;
+ * - otherwise, read result metadata in CaptureResult.result.
+ *
+ * @return queue the queue that implementation writes result metadata to.
+ */
+ getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> queue);
+
+ /**
+ * Close the offline session and release all resources.
+ *
+ * Camera service may call this method before or after the offline session
+ * has finished all requests it needs to handle. If there are still unfinished
+ * requests when close is called, camera HAL must send ERROR_REQUEST for
+ * all unfinished requests and return all buffers via
+ * ICameraDeviceCallback#processCaptureResult or
+ * ICameraDeviceCallback#returnStreamBuffers.
+ * Also, all buffer caches maintained by the offline session must be erased
+ * before the close call returns.
+ */
+ close();
+};
diff --git a/camera/device/3.6/types.hal b/camera/device/3.6/types.hal
new file mode 100644
index 0000000..743b139
--- /dev/null
+++ b/camera/device/3.6/types.hal
@@ -0,0 +1,143 @@
+/*
+ * Copyright (C) 2019 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.device@3.6;
+
+import @3.2::BufferCache;
+import @3.4::HalStream;
+
+/**
+ * OfflineRequest:
+ *
+ * Information about a capture request being switched to offline mode via the
+ * ICameraDeviceSession#switchToOffline method.
+ *
+ */
+struct OfflineRequest {
+ /**
+ * Must match a inflight CaptureRequest sent by camera service
+ */
+ uint32_t frameNumber;
+
+ /**
+ * Stream IDs for outputs that will be returned via ICameraDeviceCallback.
+ * The stream ID must be within one of offline stream listed in
+ * CameraOfflineSessionInfo.
+ * Camera service will validate these pending buffers are matching camera
+ * service's record to make sure no buffers are leaked during the
+ * switchToOffline call.
+ */
+ vec<int32_t> pendingStreams;
+};
+
+/**
+ * OfflineStream:
+ *
+ * Information about a stream being switched to offline mode via the
+ * ICameraDeviceSession#switchToOffline method.
+ *
+ */
+struct OfflineStream {
+ /**
+ * IDs of a stream to be transferred to offline session.
+ *
+ * For devices that do not support HAL buffer management, this must be
+ * one of stream ID listed in streamsToKeep argument of the
+ * switchToOffline call.
+ * For devices that support HAL buffer management, this could be any stream
+ * that was configured right before calling switchToOffline.
+ */
+ int32_t id;
+
+ /**
+ * Number of outstanding buffers that will be returned via offline session
+ */
+ uint32_t numOutstandingBuffers;
+
+ /**
+ * Buffer ID of buffers currently cached between camera service and this
+ * stream, which may or may not be owned by the camera HAL right now.
+ * See StreamBuffer#bufferId for more details.
+ */
+ vec<uint64_t> circulatingBufferIds;
+};
+
+/**
+ * CameraOfflineSessionInfo:
+ *
+ * Information about pending outputs that's being transferred to an offline
+ * session from an active session using the
+ * ICameraDeviceSession#switchToOffline method.
+ *
+ */
+struct CameraOfflineSessionInfo {
+ /**
+ * Information on what streams will be preserved in offline session.
+ * Streams not listed here will be removed by camera service after
+ * switchToOffline call returns.
+ */
+ vec<OfflineStream> offlineStreams;
+
+ /**
+ * Information for requests that will be handled by offline session
+ * Camera service will validate this matches what camera service has on
+ * record.
+ */
+ vec<OfflineRequest> offlineRequests;
+};
+
+/**
+ * HalStream:
+ *
+ * The camera HAL's response to each requested stream configuration.
+ *
+ * This version extends the @3.4 HalStream with the physicalCameraId
+ * field
+ */
+struct HalStream {
+ /**
+ * The definition of HalStream from the prior version.
+ */
+ @3.4::HalStream v3_4;
+
+ /**
+ * Whether this stream can be switch to offline mode.
+ *
+ * For devices that does not support the OFFLINE_PROCESSING capability, this
+ * fields will always be false.
+ *
+ * For devices support the OFFLINE_PROCESSING capability: any input stream
+ * and any output stream that can be output of the input stream must set
+ * this field to true. Also any stream of YUV420_888 format or JPEG format,
+ * with CPU_READ usage flag, must set this field to true. All other streams
+ * are up to camera HAL to advertise support or not, though it is not
+ * recommended to list support for streams with hardware composer or video
+ * encoder usage flags as these streams tend to be targeted continuously and
+ * can lead to long latency when trying to switch to offline.
+ *
+ */
+ bool supportOffline;
+};
+
+/**
+ * HalStreamConfiguration:
+ *
+ * Identical to @3.4::HalStreamConfiguration, except that it contains @3.6::HalStream entries.
+ *
+ */
+struct HalStreamConfiguration {
+ vec<HalStream> streams;
+};