// Copyright 2025 The ODML Authors.
//
// 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.

syntax = "proto2";

package litert.lm.proto;

// Represents external files used by the engines (e.g. TF Lite flatbuffers). The
// files can be specified by one of the following three ways:
//
// (1) file contents loaded in `file_content`.
// (2) file path in `file_name`.
// (3) file descriptor through `file_descriptor_meta` as returned by open(2).
// (4) file pointer and length in memory through `file_pointer_meta`.
//
// If more than one field of these fields is provided, they are used in this
// precedence order.
// Next id: 5
message ExternalFile {
  // The file contents as a byte array.
  optional bytes file_content = 1;

  // The path to the file to open and mmap in memory
  optional string file_name = 2;

  // The file descriptor to a file opened with open(2), with optional additional
  // offset and length information.
  optional FileDescriptorMeta file_descriptor_meta = 3;

  // The pointer points to location of a file in memory. Use the util method,
  // `SetExternalFile` in [1], to configure `file_pointer_meta` from a
  // `std::string_view` object.
  //
  // [1]: mediapipe/tasks/cc/metadata/utils/zip_utils.h
  optional FilePointerMeta file_pointer_meta = 4;
}

// A proto defining file descriptor metadata for mapping file into memory using
// mmap(2).
message FileDescriptorMeta {
  // File descriptor as returned by open(2).
  optional int32 fd = 1;

  // Optional length of the mapped memory. If not specified, the actual file
  // size is used at runtime.
  //
  // This is an advanced option, e.g. this can be used on Android to specify the
  // length of a given asset obtained from AssetFileDescriptor#getLength().
  optional int64 length = 2;

  // Optional starting offset in the file referred to by the file descriptor
  // `fd`.
  //
  // This is an advanced option, e.g. this can be used on Android to specify the
  // offset of a given asset obtained from AssetFileDescriptor#getStartOffset().
  optional int64 offset = 3;
}

// The pointer points to location of a file in memory. Make sure the file memory
// that it points locates on the same machine and it outlives this
// FilePointerMeta object.
message FilePointerMeta {
  // Memory address of the file in decimal.
  optional uint64 pointer = 1;

  // File length.
  optional int64 length = 2;
}