chromium/chromeos/services/chromebox_for_meetings/public/mojom/xu_camera.mojom

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// API for CfM to control camera functionalities in Chrome via UVC
// Extension Unit (XU) Controls.
//
// Note: This mojom should be kept in sync with the copy on the client
// side. See: go/meet-xu-client.
//
// Next MinVersion: 1

module ash.cfm.mojom;

// Identifies the webcam through its WebRtc id or device node path.
union WebcamId {
  // WebRtc ID
  string device_id;
  // Device Node path
  string dev_path;
};

// Indicates which low-level UVC XU Control request.
enum GetFn {
  // Obtain the current value of the control.
  kCur = 0,

  // Obtain the minimum value of the control.
  kMin,

  // Obtain the minimum value of the control.
  kMax,

  // Obtain the default value of the control.
  kDef,

  // Query the resolution of the control,
  // i.e. the step size of the allowed control values.
  kRes,

  // Query the size of the control in bytes.
  kLen,

  // Query the control information bitmap,
  // which indicates whether get/set
  // requests are supported.
  kInfo,
};

// UVCMenuInfo
struct MenuInfo {
  // Menu entry value used by device.
  uint32 value;

  // Menu entry name.
  array<uint8, 32> name;
};

// UVCMenuEntries
struct MenuEntries {
  // Array of menu entries (for menu controls only)
  array<MenuInfo> menu_info;
};

// UvcXUControlMapping
struct ControlMapping {
  // V4L2 control identifier
  uint32 id;

  // V4L2 control name
  array<uint8, 32> name;

  // UVC extension unit GUID (little-endian)
  array<uint8, 16> guid;

  // UVC control selector
  uint8 selector;

  // V4L2 control size (in bits)
  uint8 size;

  // V4L2 control offset (in bits)
  uint8 offset;

  // V4L2 control type
  uint32 v4l2_type;

  //  UVC control data type
  uint32 data_type;

  // Optional UVC Menu Entries
  MenuEntries? menu_entries;
};

// UvcXUControlQuery
struct ControlQuery {
  // UVC extension unit
  uint8 unit_id;

  // UVC control selector
  uint8 selector;
};

// UvciocCtrlType
union CtrlType {
  // UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
  ControlMapping mapping_ctrl;

  // UVCIOC_CTRL_QUERY - Query a UVC XU control
  ControlQuery query_ctrl;
};

// Interface used to query UVC XU controls
interface XuCamera {
  // Attempts to find the Local UnitID from the GUID
  //
  // The request:
  // * |id| - webcam id, either a WebRtc id or a device node path.
  // * |guid| - UVC XU GUID (little-endian).
  //
  // The response:
  // * |error_code| - zero if successful and non-zero if failed or invalid.
  // * |unit_id| - unit ID value corresponding to guid
  GetUnitId(WebcamId id, array<uint8, 16> guid) => (uint8 error_code,
                                                     uint8 unit_id);

  // Maps a UVC control to a V4L2 control.
  // Note: Not required before using |GetCtrl| or |SetCtrl|
  MapCtrl(WebcamId id, ControlMapping mapping_ctrl) => (uint8 error_code);

  // Obtains a value of an XU control given the getter function.
  //
  // The request:
  // * |id| - webcam id, either a WebRtc id or a device node path.
  // * |ctrl| - control type, either the mapping or query.
  // * |fn| - getter function, i.e. current, min, max value of control.
  //
  // The response:
  // * |error_code| - zero if successful and non-zero if failed or invalid.
  // * |data| - data requested by the GetFn.
  GetCtrl(WebcamId id, CtrlType ctrl, GetFn fn) => (uint8 error_code,
                                                     array<uint8> data);

  // Updates the value of a device's XU control.
  //
  // The request:
  // * |id| - webcam id, either a WebRtc id or a device node path.
  // * |ctrl| - control type, either the mapping or query.
  // * |data| - the new value of the device's XU control.
  //
  // The response:
  // * |error_code| - zero if successful and non-zero if failed or invalid.
  SetCtrl(WebcamId id, CtrlType ctrl, array<uint8> data) => (uint8 error_code);
};