iree/schemas/bytecode_module_def.fbs

// Copyright 2019 The IREE Authors
//
// Licensed under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

namespace iree.vm;

// IREE bytecode module.
file_identifier "IREE";
file_extension "vmfb";

// Arbitrary key/value reflection attribute.
table ReflectionAttrDef {
  key:string;
  value:string;
}

// Defines a type within the type table.
table TypeDef {
  // Fully-qualified name of the type, such as `hal.buffer`.
  full_name:string;
}

// Defines a function signature.
table FunctionSignatureDef {
  // Arguments, in order, as described in the FunctionSignatureDef.
  // Maps to an entry in the module type table.
  argument_types:[int32];

  // Results, in order, as described in the FunctionSignatureDef.
  // Maps to an entry in the module type table.
  result_types:[int32];

  // The VM calling convention declaration used to marshal arguments and
  // results into and out of the function.
  // Optional for imports and internal functions but required for exports.
  //
  // See iree/vm/module.h for more information.
  calling_convention:string;

  // Function level reflection attributes.
  // These are typically used to communicate additional ABI metadata needed
  // for dynamic invocation and host language mapping.
  // See: docs/developers/design_docs/function_abi.md
  reflection_attrs:[ReflectionAttrDef];
}

// Defines a runtime-resolved import function.
table ImportFunctionDef {
  // Fully-qualified name of the function (including the module namespace).
  full_name:string;

  // Signature of the function expected used for verifying that imports match.
  signature:FunctionSignatureDef;
}

// Defines a runtime-resolved export function.
table ExportFunctionDef {
  // Local name of the function (excluding the module namespace).
  local_name:string;

  // Signature of the function expected used for verifying that imports match.
  signature:FunctionSignatureDef;

  // Ordinal in the internal_functions table that implements this function.
  internal_ordinal:int32;
}

// Defines a bytecode function.
table InternalFunctionDef {
  // Local name of the function or empty if the names have been stripped.
  // The full name of the function when referenced from external modules will
  // include the BytecodeModuleDef.name prefix.
  local_name:string;

  // Signature of the function used for reflection.
  signature:FunctionSignatureDef;
}

table UncompressedDataDef {
}

union CompressionTypeDef {
  UncompressedDataDef,
}

// Read-only data segment.
table RodataSegmentDef {
  // The compression format used for the data, including required decompression
  // arguments. Omitted if the data is uncompressed.
  compression_type:CompressionTypeDef;

  // Contents in a format defined by CompressionTypeDef.
  data:[uint8];
}

// Read-write data segment.
table RwdataSegmentDef {
  // Total byte capacity.
  byte_size:int32;
}

// Defines the per-instance module state.
table ModuleStateDef {
  // Bytes used for global primitive value storage. All are initialized to zero
  // on module state allocation.
  global_bytes_capacity:int32;

  // Total number of global ref values.
  global_ref_count:int32;
}

// Static function descriptor used for stack frame allocation.
struct FunctionDescriptor {
  // Offset and length within the larger bytecode data block.
  bytecode_offset:int32;
  bytecode_length:int32;

  // TODO(benvanik): remove counts and embed directly in bytecode.
  // Total number of i32 registers used by the function.
  i32_register_count:int16;
  // Total number of ref registers used by the function.
  ref_register_count:int16;
}

// mlir/IR/BuiltinLocationAttributes.td : CallSiteLoc
table CallSiteLocDef {
  callee:int32;
  caller:int32;
}

// mlir/IR/BuiltinLocationAttributes.td : FileLineColLoc
table FileLineColLocDef {
  filename:string;
  line:int32;
  column:int32;
}

// mlir/IR/BuiltinLocationAttributes.td : FusedLoc
table FusedLocDef {
  metadata:string;
  locations:[int32];
}

// mlir/IR/BuiltinLocationAttributes.td : FusedLoc
table NameLocDef {
  name:string;
  child_location:int32;
}

// A location - possibly nested.
union LocationTypeDef {
  CallSiteLocDef,
  FileLineColLocDef,
  FusedLocDef,
  NameLocDef,
}

// Maps a relative bytecode offset within a function to a source location.
struct BytecodeLocationDef {
  // Bytecode offset of the start of the operation.
  bytecode_offset:int32;
  // Index into the debug database location_table.
  location:int32;
}

// Debug data for a single function mapping back into source IR.
table FunctionSourceMapDef {
  // Operation locations for all ops within the function.
  locations:[BytecodeLocationDef];
}

// VM debug information database.
table DebugDatabaseDef {
  // Location table. Source maps reference this table.
  location_table:[LocationTypeDef];

  // Internal function source maps; 1:1 with the module function_descriptors.
  functions:[FunctionSourceMapDef];
}

// Defines a bytecode module containing the information required to serve the
// iree_vm_module_interface_t interface.
//
// Modules are similar to shared objects in that they provide a set of exported
// functions that can be queried and called externally as well as any number of
// internal function definitions. Imports can also be used to have the loader
// dynamically link in exports of other modules upon loading.
//
// Modules can contain read-only segments containing (optionally) compressed
// data that is used by the module. Read-write segments define uninitialized
// reservations and are similar to .bss, and custom initializer functions can
// be embedded to treat them as if they were .data segments.
//
// State can be defined per active runtime context (effectively like
// thread-local storage) using ModuleStateDef. The runtime will prepare this
// state and maintain it for the lifetime of contexts and ensure that ops that
// use it (such as vm.global.load.*) are always associated with the appropriate
// state.
table BytecodeModuleDef {
  // Module namespace used for fully-qualified function lookups.
  name:string (required);

  // Type table mapping type IDs used within the module to type signatures.
  types:[TypeDef];

  // Imported function definitions used to resolve imports.
  imported_functions:[ImportFunctionDef];

  // Exported function definitions used to resolve imports.
  exported_functions:[ExportFunctionDef];

  // All functions with internal linkage.
  internal_functions:[InternalFunctionDef];

  // Read-only data segments (like non-code .text).
  // May optionally be compressed and decompressed by the loader.
  rodata_segments:[RodataSegmentDef];

  // Read-write data segments of uninitialized memory (like .bss).
  rwdata_segments:[RwdataSegmentDef];

  // Global module state information (like TLS).
  module_state:ModuleStateDef;

  // References to ranges in the bytecode contents buffer where each internal
  // function is located. This table is kept unnested within InternalFunctionDef
  // to avoid the need to walk the FlatBuffer hierarchy at runtime when
  // resolving call targets. Multiple functions may alias the same ranges in
  // bytecode_data.
  function_descriptors:[FunctionDescriptor];

  // Bytecode contents. One large buffer containing all of the function op data.
  bytecode_data:[uint8];

  // Optional module debug database.
  debug_database:DebugDatabaseDef;
}

root_type BytecodeModuleDef;