media: add video capture device for ARC++ camera HAL v3

media/capture/video/chromeos/mojo/arc_camera3.mojom

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+module arc.mojom;
+
+import "arc_camera3_metadata.mojom";
+
+[Extensible]
+enum HalPixelFormat {
+  HAL_PIXEL_FORMAT_RGBA_8888 = 0x1,
+  HAL_PIXEL_FORMAT_RGBX_8888 = 0x2,
+  HAL_PIXEL_FORMAT_BGRA_8888 = 0x5,
+  HAL_PIXEL_FORMAT_YCrCb_420_SP = 0x11,
+  HAL_PIXEL_FORMAT_YCbCr_422_I = 0x14,
+  HAL_PIXEL_FORMAT_BLOB = 0x21,
+  HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22,
+  HAL_PIXEL_FORMAT_YCbCr_420_888 = 0x23,
+  HAL_PIXEL_FORMAT_YV12 = 0x32315659,
+};
+
+// The following enums are from Android's camera HAL v3 API header.
+// (hardware/libhardware/include/hardware/camera3.h)
+
+enum CameraFacing {
+  CAMERA_FACING_BACK = 0,
+  CAMERA_FACING_FRONT = 1,
+  CAMERA_FACING_EXTERNAL = 2,
+};
+
+enum Camera3StreamType {
+  CAMERA3_STREAM_OUTPUT = 0,
+  CAMERA3_STREAM_INPUT = 1,
+  CAMERA3_STREAM_BIDIRECTIONAL = 2,
+  CAMERA3_NUM_STREAM_TYPES,
+};
+
+enum Camera3StreamRotation {
+  CAMERA3_STREAM_ROTATION_0 = 0,
+  CAMERA3_STREAM_ROTATION_90 = 1,
+  CAMERA3_STREAM_ROTATION_180 = 2,
+  CAMERA3_STREAM_ROTATION_270 = 3,
+};
+
+[Extensible]
+enum Camera3StreamConfigurationMode {
+  CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0,
+  CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE =1,
+  CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000,
+};
+
+[Extensible]
+enum Camera3RequestTemplate {
+  CAMERA3_TEMPLATE_PREVIEW = 1,
+  CAMERA3_TEMPLATE_STILL_CAPTURE = 2,
+  CAMERA3_TEMPLATE_VIDEO_RECORD = 3,
+  CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4,
+  CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5,
+  CAMERA3_TEMPLATE_MANUAL = 6,
+  CAMERA3_TEMPLATE_COUNT,
+  CAMERA3_VENDOR_TEMPLATE_START = 0x40000000,
+};
+
+enum Camera3BufferStatus {
+  CAMERA3_BUFFER_STATUS_OK = 0,
+  CAMERA3_BUFFER_STATUS_ERROR = 1,
+};
+
+enum Camera3MsgType {
+  CAMERA3_MSG_ERROR = 1,
+  CAMERA3_MSG_SHUTTER = 2,
+  CAMEAR3_NUM_MESSAGES,
+};
+
+struct Camera3Stream {
+  uint64 id;
+  Camera3StreamType stream_type;
+  uint32 width;
+  uint32 height;
+  HalPixelFormat format;
+  uint32 usage;
+  uint32 max_buffers;
+  uint32 data_space;
+  Camera3StreamRotation rotation;
+};
+
+struct Camera3StreamConfiguration {
+  uint32 num_streams;
+  array<Camera3Stream> streams;
+  Camera3StreamConfigurationMode operation_mode;
+  int32 error;  // Used to piggyback error code returned by driver.
+};
+
+struct Camera3StreamBuffer {
+  uint64 stream_id;
+  uint64 buffer_id;
+  Camera3BufferStatus status;
+  handle? acquire_fence;
+  handle? release_fence;
+};
+
+struct Camera3CaptureRequest {
+  uint32 frame_number;
+  CameraMetadata settings;
+  Camera3StreamBuffer? input_buffer;
+  uint32 num_output_buffers;
+  array<Camera3StreamBuffer> output_buffers;
+};
+
+interface Camera3DeviceOps {

[chfremer, 2017/04/27 22:41:41]

I see that there are documenting comments in the C++ class headers.
As a reader, I would find it more useful to see some of the documentation here
with the interface.
From reading the interface, I would like to get a rough idea of what the typical
communication protocol between the Chromium side and the HAL service side is.

[jcliang, 2017/04/28 04:47:57]

I'll add some comments to briefly explain the flow of the IPC.

+  Initialize@0(Camera3CallbackOps callback_ops) => (int32 result);
+
+  ConfigureStreams@1(Camera3StreamConfiguration config) =>
+      (Camera3StreamConfiguration updated_config);
+
+  ConstructDefaultRequestSettings@2(Camera3RequestTemplate type) =>
+      (CameraMetadata? settings);
+
+  ProcessCaptureRequest@3(Camera3CaptureRequest request) => (int32 result);
+
+  Dump@4(handle fd);
+
+  Flush@5() => (int32 result);
+
+  enum BufferType {
+    GRALLOC = 0,  // gralloc buffer. Needs to be imported through GBM.
+    SHM = 1,      // shared memory buffer. Can be mmapped directly.
+    // Add DMABUF when needed.
+  };
+
+  RegisterBuffer@6(uint64 buffer_id, BufferType type, array<handle> fds,

[chfremer, 2017/04/27 22:41:41]

It seems the buffers are specific to a particular format, probably I420. Why is
that needed? Wouldn't it suffice to just specify a size in bytes for the buffer
and keep information about what format is being used separate? 

What about MJPEG?

[jcliang, 2017/04/28 04:47:58]

This mojom is used by both Android and Chrome to talk to the HAL adapter process
on Chrome OS.

This RegisterBuffer interface is needed on the Android side: we need to use some
special logic to extract information from the device-specific gralloc buffer
handle at Android and pass the info to HAL adapter on Chrome OS to reconstruct
the buffer handle. On Android there may be multiple streams active at the same
time using different types of buffers. The params in RegisterBuffer interface
encapsulates all the required info to create a gralloc buffer handle of any
type.

For Chrome the buffer handling is much simpler and you're probably right that we
can simply pass the size of the buffer and keep the buffer info elsewhere, but
we would want to use the same Mojo IPC interface as Android.

+                   uint32 drm_format, HalPixelFormat hal_pixel_format,
+                   uint32 width, uint32 height, array<uint32> strides,
+                   array<uint32> offsets) =>
+      (int32 result);
+
+  Close@7() => (int32 result);
+};
+
+struct Camera3CaptureResult {
+  uint32 frame_number;
+  CameraMetadata result;
+  uint32 num_output_buffers;
+  array<Camera3StreamBuffer>? output_buffers;
+  Camera3StreamBuffer? input_buffer;
+  uint32 partial_result;
+};
+
+struct Camera3ErrorMsg {
+  uint32 frame_number;
+  uint64 error_stream_id;
+  int32 error_code;
+};
+
+struct Camera3ShutterMsg {
+  uint32 frame_number;
+  uint64 timestamp;
+};
+
+union Camera3NotifyMsgMessage {
+  Camera3ErrorMsg error;
+  Camera3ShutterMsg shutter;
+  array<uint8> generic;
+};
+
+struct Camera3NotifyMsg {
+  Camera3MsgType type;
+  Camera3NotifyMsgMessage message;
+};
+
+interface Camera3CallbackOps {
+  ProcessCaptureResult@0(Camera3CaptureResult result);
+
+  Notify@1(Camera3NotifyMsg msg);
+};
+
+struct CameraInfo {
+  CameraFacing facing;
+  int32 orientation;
+  uint32 device_version;
+  CameraMetadata static_camera_characteristics;
+  // resource cost is not valid in CAMERA_MODULE_API_VERSION_2_3 or lower.
+  // conflicting_devices is not valid in CAMERA_MODULE_API_VERSION_2_3 or lower.
+  // conflicting_devices_length is not valid in CAMERA_MODULE_API_VERSION_2_3 or lower.
+};
+
+interface CameraModule {
+  OpenDevice@0(int32 camera_id) => (int32 result, Camera3DeviceOps? device_ops);
+
+  GetNumberOfCameras@1() => (int32 result);
+
+  GetCameraInfo@2(int32 camera_id) => (int32 result, CameraInfo? camera_info);
+
+  SetCallbacks@3(CameraModuleCallbacks callbacks) => (int32 result);
+};
+
+enum CameraDeviceStatus {
+  CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
+  CAMERA_DEVICE_STATUS_PRESENT = 1,
+  CAMERA_DEVICE_STATUS_ENUMERATING = 2,
+};
+
+interface CameraModuleCallbacks {
+  CameraDeviceStatusChange@0(int32 camera_id, CameraDeviceStatus new_status);
+};