ml/mojom/model.mojom

// Copyright 2018 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.

// Next MinVersion: 2

// Datatypes and interfaces of models for the Machine Learning API.

// NOTE: This mojom exists in two places and must be kept in sync:
//       Chromium:  //chromeos/services/machine_learning/public/mojom/
//       Chrome OS: src/platform2/ml/mojom/
//       Note: Other repos downstream of Chromium might also use this mojom.
// Example: A backwards-compatible mojom change (and corresponding
// implementation change) can be made in Chrome OS first, then replicated to the
// clients (Chromium, other downstream repos) later.
// Use //chromeos/services/machine_learning/public/mojom/roll_mojoms.sh to help
// replicate Chrome OS-side changes over to Chromium.

module chromeos.machine_learning.mojom;

// NOTE: The base directory for 'import' statements is expected to differ
//       between Chromium and Chrome OS versions of this file.
import "ml/mojom/graph_executor.mojom";

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// ModelIds prefixed with UNSUPPORTED_ are no longer supported. Attempts to load
// them will produce an error.
[Stable, Extensible]
enum BuiltinModelId {
  // Unknown ML model. It is marked as unsupported.
  UNSUPPORTED_UNKNOWN = 0,
  // Test ML model.
  TEST_MODEL = 1,
  // The Smart Dim (20181115) ML model.
  UNSUPPORTED_SMART_DIM_20181115 = 2,
  // The Smart Dim (20190221) ML model.
  UNSUPPORTED_SMART_DIM_20190221 = 3,
  // The Top Cat (20190722) ML model.
  UNSUPPORTED_TOP_CAT_20190722 = 4,
  // The Smart Dim (20190521) ML model.
  SMART_DIM_20190521 = 5,
  // The Search Ranker (20190923) ML model.
  SEARCH_RANKER_20190923 = 6,
  // The Adaptive Charging (20211105) ML model.
  [MinVersion=1] ADAPTIVE_CHARGING_20211105 = 7,
};

// Graphics API to use with the GPU delegate.
[Stable, Extensible]
enum GpuDelegateApi {
  // Unknown value or not specified.
  [Default] UNKNOWN = 0,

  // Use OpenGL.
  OPENGL = 1,

  // Use OpenCL.
  OPENCL = 2,
};

// Options for creating the executor.  Options are used for testing and
// development. They are not typically used in normal, production code.
[Stable]
struct GraphExecutorOptions {
  // Use NNAPI delegate.
  bool use_nnapi = false;

  // Use GPU delegate.
  [MinVersion=1] bool use_gpu = false;

  // Graphics API to use with GPU delegate.
  [MinVersion=1] GpuDelegateApi gpu_delegate_api = OPENGL;
};

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
[Stable, Extensible]
enum CreateGraphExecutorResult {
  OK = 0,
  MODEL_INTERPRETATION_ERROR = 1,
  MEMORY_ALLOCATION_ERROR = 2,
  NNAPI_UNAVAILABLE = 3,
  NNAPI_USE_ERROR = 4,
  [MinVersion=1] GPU_UNAVAILABLE = 5,
  [MinVersion=1] GPU_USE_ERROR = 6,
  [MinVersion=1] DELEGATE_CONFIG_ERROR = 7,
  [MinVersion=1] NOT_FULLY_DELEGABLE = 8,
};

// Model specification for builtin models.
// Because ml-service can retrieve a builtin model's content and metadata, only
// an `id` is needed to specify it.
[Stable]
struct BuiltinModelSpec {
  BuiltinModelId id;
};

// Model specification for downloaded models.
// For a downloaded model, both of the model content and metadata must be
// specified.
[Stable]
struct FlatBufferModelSpec {
  // The content of the model's tflite model file.
  string model_string;
  // A map from input nodes' names to their indices.
  map<string, int32> inputs;
  // A map from output nodes' names to their indices.
  map<string, int32> outputs;
  // Used in naming the UMA metric histograms of the model. An example of the
  // names of the histograms is:
  //
  // MachineLearningService.`metrics_model_name`.ExecuteResult.CpuTimeMicrosec
  //
  // This variable must NOT be empty.
  string metrics_model_name;
};

// The lifetime of the cached model is tied to the lifetime of the Model
// interface pipe. The Model interface pipe can be used to acquire multiple
// separate GraphExecutor instances.
// Next ordinal: 2
[Stable]
interface Model {
  // Deprecated messages:
  REMOVED_0@0(pending_receiver<GraphExecutor> receiver) =>
      (CreateGraphExecutorResult result);

  // Creates a new GraphExecutor with the specified `options` and binds it to
  // `receiver`. The GraphExecutor can be used to repeatedly evaluate this
  // `Model`.
  // * A Model can have more than one GraphExecutor.
  // * Releasing this GraphExecutor frees the associated memory (but
  //   doesn't free the Model unless its pipe is also closed).
  CreateGraphExecutor@1(GraphExecutorOptions options,
                        pending_receiver<GraphExecutor> receiver) =>
      (CreateGraphExecutorResult result);
};