sdk/banjo/fuchsia.hardware.camera.sensor/camera-sensor.fidl

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.hardware.camera.sensor;

using fuchsia.hardware.camera;
using zx;

const EXTENSION_VALUE_ARRAY_LEN uint32 = 32;

/// A type used to distinguish extension parameters.
type ExtensionValueDataType = strict union {
    1: int_value int32;
    2: uint_value uint32;
    3: byte_array_value array<uint8, EXTENSION_VALUE_ARRAY_LEN>;
    4: dimension_value fuchsia.hardware.camera.Dimensions;
    5: constraints_value fuchsia.hardware.camera.MinMaxConstraints;
    6: frame_rate_info_value array<FrameRateInfo, EXTENSION_VALUE_ARRAY_LEN>;
};

type PixelType = strict enum : uint8 {
    RAW8 = 1;
    RAW10 = 2;
    RAW12 = 3;
};

type DynamicRangeMode = strict enum : uint8 {
    LINEAR = 1;
    WIDE = 2;
};

type BinningMode = strict enum : uint8 {
    NONE = 1;
    ADDITIVE = 2;
    AVERAGE = 3;
};

type SamplingParams = struct {
    mode BinningMode;
    bin_amount uint32;
    skip_amount uint32;
};

type ReadoutConfig = struct {
    /// Describes sampling parameters for the x plane.
    sampling_x SamplingParams;
    /// Describes sampling parameters for the y plane.
    sampling_y SamplingParams;
    /// The x and y offset as well as the width and height for cropping.
    scaler_crop fuchsia.hardware.camera.Rect;
};

/// A sensor can support several different predefined modes.
/// This structure keeps all necessary information about a mode.
// TODO(fxbug.dev/55427): Move non-sensor-specific params out of this struct.
type OperatingMode = struct {
    /// This mode's index.
    idx uint8;
    /// This mode's identifying string.
    identifier string:MAX;
    /// Maximum frames per second.
    fps uint32;
    /// Input resolution, where |x| is pixel width and |y| is pixel height.
    resolution_in fuchsia.hardware.camera.Dimensions;
    /// Output resolution, where |x| is pixel width and |y| is pixel height.
    resolution_out fuchsia.hardware.camera.Dimensions;
    /// How many exposures this mode supports.
    exposures uint8;
    /// A mode that reflects what dynamic range technique is being used.
    dr_mode DynamicRangeMode;
    /// The pixel type (e.g. whether the output is in RAW8, RAW10, etc. format).
    pixel_type PixelType;
    /// Lane count.
    lanes uint8;
    /// MBps per lane.
    mbps uint32;
    /// Line time.
    line_time float32;
    /// Frame time.
    frame_time float32;
    /// A structure containing information on binning, skipping, and scaling
    /// operations carried out on frame data.
    readout ReadoutConfig;
};

/// This structure maps the sensor's frame rates to coarse max integration time.
type FrameRateInfo = struct {
    frame_rate fuchsia.hardware.camera.FrameRate;
    max_coarse_integration_time uint32;
};

// TODO(fxbug.dev/55428): Incorporate muting behavior into documentation. Add arg/return value info.
// TODO(fxbug.dev/56558): Add a versioning mechanism.
// TODO(fxbug.dev/55430): Transition methods to use [Async].
/// Exposes a product-agnostic interface to the camera's sensor.
/// Allows clients to get and set sensor constraints, sensor mode,
/// and its dynamic operating state.
///
/// Most methods provide a `zx.status` return value. This can be:
///    ZX_OK                      - The operation was successful.
///    ZX_ERR_INTERNAL            - The sensor has not been initialized or has encountered an
///                                 otherwise unspecified error.
///    ZX_ERR_NOT_SUPPORTED       - The operation is not supported on the current device.
///    ZX_ERR_INVALID_ARGS        - Invalid args for this operation.
///    ZX_ERR_OUT_OF_RANGE        - Args fall outside of min/max constraints.
///    ZX_ERR_BUFFER_TOO_SMALL    - Buffer provided cannot hold all required data.
///    ZX_ERR_IO_NOT_PRESENT      - There is no sensor device present or bound.
@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol CameraSensor2 {
    /// Initializes the sensor.
    Init() -> (struct {
        s zx.status;
    });
    /// De-Initializes the sensor.
    DeInit() -> ();

    /// Retrieves the sensor's ID.
    GetSensorId() -> (struct {
        s zx.status;
        id uint32;
    });

    /// Retrieve a vector of available modes.
    GetAvailableModes() -> (struct {
        s zx.status;
        modes vector<OperatingMode>:MAX;
    });
    /// Use a specific mode for the initialization sequence.
    SetMode(struct {
        mode uint32;
    }) -> (struct {
        s zx.status;
    });

    /// Start streaming.
    /// Is safe to call this if streaming is already started.
    StartStreaming() -> (struct {
        s zx.status;
    });
    /// Stop streaming.
    /// It is safe to call this if streaming is already stopped.
    StopStreaming() -> ();

    // Exposure Settings

    /// Retrieve analog gain value.
    GetAnalogGain() -> (struct {
        s zx.status;
        gain float32;
    });
    /// Changes analog gain value.
    SetAnalogGain(struct {
        gain float32;
    }) -> (struct {
        s zx.status;
        gain float32;
    });
    /// Retrieve digital gain value.
    GetDigitalGain() -> (struct {
        s zx.status;
        gain float32;
    });
    /// Changes digital gain value.
    SetDigitalGain(struct {
        gain float32;
    }) -> (struct {
        s zx.status;
        gain float32;
    });
    /// Retrieve integration time value.
    GetIntegrationTime() -> (struct {
        s zx.status;
        int_time float32;
    });
    /// Changes Integration Time.
    SetIntegrationTime(struct {
        int_time float32;
    }) -> (struct {
        s zx.status;
        int_time float32;
    });

    /// Update the sensor with new parameters.
    Update() -> (struct {
        s zx.status;
    });

    // OTP

    /// Retrieve the total size of the data stored in the OTP module.
    GetOtpSize() -> (struct {
        s zx.status;
        size uint32;
    });
    /// Retrieve the specified amount of OTP data at the offset and write them to
    /// the provided vmo.
    GetOtpData(struct {
        byte_count uint32;
        offset uint32;
    }) -> (resource struct {
        s zx.status;
        otp_data zx.handle:VMO;
    });

    // Test Controls

    /// Retrieves the test pattern mode the sensor is set to.
    ///    0            – No pattern (default)
    ///    1            – Solid colour
    ///    2            – 100% colour bars
    ///    3            – Fade to grey’ colour bars
    ///    4            - PN9
    ///    5-255        - Reserved
    ///    256-65535    – Manufacturer specific
    GetTestPatternMode() -> (struct {
        s zx.status;
        value uint16;
    });
    /// Changes the sensor's test pattern mode.
    SetTestPatternMode(struct {
        mode uint16;
    }) -> (struct {
        s zx.status;
    });
    /// Retrieves the test pattern data being used.
    GetTestPatternData() -> (struct {
        s zx.status;
        data fuchsia.hardware.camera.ColorVal;
    });
    /// Changes data used by the test pattern. Only used by certain modes.
    SetTestPatternData(struct {
        data fuchsia.hardware.camera.ColorVal;
    }) -> (struct {
        s zx.status;
    });

    /// Retrieves the test cursor data being used.
    GetTestCursorData() -> (struct {
        s zx.status;
        data fuchsia.hardware.camera.Rect;
    });
    /// Changes the sensor's cursor-related parameters.
    SetTestCursorData(struct {
        data fuchsia.hardware.camera.Rect;
    }) -> (struct {
        s zx.status;
    });

    // Other Capabilities

    /// This subset of the API provides implementers with the flexibility to provide custom
    /// endpoints for elements not otherwise included.
    /// Retrieves the specified element. The caller must reference the implementer's ID list.
    GetExtensionValue(struct {
        id uint64;
    }) -> (struct {
        s zx.status;
        value ExtensionValueDataType;
    });
    /// This subset of the API provides implementers with the flexibility to provide custom
    /// endpoints for elements not otherwise included.
    /// Changes the specified element. The caller must reference the implementer's ID list.
    SetExtensionValue(struct {
        id uint64;
        value ExtensionValueDataType;
    }) -> (struct {
        s zx.status;
        value ExtensionValueDataType;
    });
};