blob: 3a917acc6010d68b89ea15223d4db5f1a3a89463 [file] [log] [blame]
// Copyright 2017 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.
module memory_instrumentation.mojom;
import "mojo/common/process_id.mojom";
// Common structs:
enum DumpType {
PERIODIC_INTERVAL,
EXPLICITLY_TRIGGERED,
PEAK_MEMORY_USAGE,
SUMMARY_ONLY
};
enum LevelOfDetail {
BACKGROUND,
LIGHT,
VM_REGIONS_ONLY_FOR_HEAP_PROFILER,
DETAILED
};
enum ProcessType {
OTHER,
BROWSER,
RENDERER,
GPU,
UTILITY,
PLUGIN
};
enum HeapProfilingMode {
DISABLED,
TASK_PROFILER,
BACKGROUND,
PSEUDO_STACK,
NATIVE_STACK
};
// These structs are internal only (only for the communication between
// the service and the ClientProcess library).
// See corresponding types in //base/trace_event for comments.
struct RequestArgs {
uint64 dump_guid;
DumpType dump_type;
LevelOfDetail level_of_detail;
};
struct RawAllocatorDumpEdge {
uint64 source_id;
uint64 target_id;
int64 importance;
bool overridable;
};
union RawAllocatorDumpEntryValue {
uint64 value_uint64;
string value_string;
};
struct RawAllocatorDumpEntry {
string name;
string units;
RawAllocatorDumpEntryValue value;
};
struct RawAllocatorDump {
uint64 id;
string absolute_name;
bool weak;
LevelOfDetail level_of_detail;
array<RawAllocatorDumpEntry> entries;
};
struct RawProcessMemoryDump {
LevelOfDetail level_of_detail;
array<RawAllocatorDumpEdge> allocator_dump_edges;
array<RawAllocatorDump> allocator_dumps;
};
struct VmRegion {
const uint32 kProtectionFlagsRead = 4;
const uint32 kProtectionFlagsWrite = 2;
const uint32 kProtectionFlagsExec = 1;
const uint32 kProtectionFlagsMayshare = 128;
uint64 start_address;
uint64 size_in_bytes;
uint64 module_timestamp;
uint32 protection_flags;
string mapped_file;
// private_dirty_resident + private_clean_resident + shared_dirty_resident +
// shared_clean_resident = resident set size.
uint64 byte_stats_private_dirty_resident;
uint64 byte_stats_private_clean_resident;
uint64 byte_stats_shared_dirty_resident;
uint64 byte_stats_shared_clean_resident;
uint64 byte_stats_swapped;
// For multiprocess accounting.
uint64 byte_stats_proportional_resident;
};
// Platform-specific data that will be used to compute the
// PrivateMemoryFootprint.
struct PlatformPrivateFootprint {
uint64 phys_footprint_bytes = 0;
// macOS 10.12+
uint64 internal_bytes = 0;
// macOS [all versions]
uint64 compressed_bytes = 0;
uint64 rss_anon_bytes = 0;
// Linux, Android, ChromeOS
uint64 vm_swap_bytes = 0;
// On Windows,
uint64 private_bytes = 0;
// On iOS,
// TBD: https://crbug.com/714961
};
struct RawOSMemDump {
uint32 resident_set_kb = 0;
PlatformPrivateFootprint platform_private_footprint;
array<VmRegion> memory_maps;
};
// These structs are public:
struct OSMemDump {
uint32 resident_set_kb = 0;
// This is roughly private, anonymous, non-discardable, resident or swapped
// memory in kilobytes. For more details, see https://goo.gl/3kPb9S.
uint32 private_footprint_kb = 0;
// This is roughly non-private, anonymous, non-discardable, resident memory
// in kilobytes. For more details, see https://goo.gl/3kPb9S.
uint32 shared_footprint_kb = 0;
// This field is present only when the dump is obtained through
// Coordinator.GetVmRegionsForHeapProfiler(), empty in the generic case of
// RequestGlobalMemoryDump().
array<VmRegion> memory_maps_for_heap_profiler;
// This is private swapped memory in kilobytes reported on Linux and Android
// only.
// TODO(crbug.com/676224): add platform restrictions when preprocessing in
// mojoms is supported.
uint32 private_footprint_swap_kb = 0;
};
struct ChromeMemDump {
uint32 malloc_total_kb = 0;
uint32 command_buffer_total_kb = 0;
uint32 partition_alloc_total_kb = 0;
uint32 blink_gc_total_kb = 0;
uint32 v8_total_kb = 0;
// The allocator dumps specified by the input args.
// (See GlobalRequestArgs.allocator_dump_names).
map<string, AllocatorMemDump> entries_for_allocator_dumps;
};
// This struct contains information about a particular allocator dump
// (e.g. cc/resource_memory).
struct AllocatorMemDump {
// The entries for the allocator which are of scalar types (i.e. not strings).
// Examples include: effective_size, size, object_count.
map<string, uint64> numeric_entries;
};
// This struct is used for the public-facing API
// Coordinator::RequestGlobalMemoryDump().
struct ProcessMemoryDump {
ProcessType process_type;
OSMemDump os_dump;
ChromeMemDump chrome_dump;
// |pid| is necessary to correlate a ProcessMemoryDump with the URLs for the
// process, which is obtained from the ResourceCoordinator service. In a
// future world where both ResourceCoordinator and MemoryInstrumentation are
// less in flux, they will probably be merged into a single service, and this
// parameter can be removed.
mojo.common.mojom.ProcessId pid;
};
// This struct is returned by the public-facing API
// Coordinator::RequestGlobalMemoryDump().
struct GlobalMemoryDump {
array<ProcessMemoryDump> process_dumps;
};
// This is the interface implemented by the per-process client library. This
// allows a process to contribute to memory-infra dumps. There should be at
// most one instance of this per hosting process.
interface ClientProcess {
// When |success| == true the dump is appended in the process-local trace
// buffer of the target process and an ACK. A summary of the dump is also
// returned in case of success.
RequestChromeMemoryDump(RequestArgs args) =>
(bool success, uint64 dump_id, RawProcessMemoryDump? raw_process_memory_dump);
// Enable heap profiler in the client process.
EnableHeapProfiling(HeapProfilingMode mode) =>
(bool success);
// Requests an OSMemDump for each pid in |pids|.
// The Memory-infra service deals with two kinds of information:
// 1) Chrome's view of its own memory use (recorded as ChromeMemDumps)
// 2) The OS's view of Chrome's memory use (recorded as OSMemDumps)
// Both of these are collected per process. On most platforms each process
// can make the system calls to collect its own OSMemDump however on some
// platforms *cough* Linux *cough* due to sandboxing only the browser
// process can collect OSMemDumps. This API allows for these two cases.
// On most platforms we send this message to each ClientProcess with
// with one pid - kNullProcessId - meaning return just your own OSMemDump.
// On Linux we call this once on the browser process ClientProcess passing
// the pids for all processes.
// See crbug.com/461788
RequestOSMemoryDump(bool want_mmaps, array<mojo.common.mojom.ProcessId> pids) =>
(bool success, map<mojo.common.mojom.ProcessId, RawOSMemDump> dumps);
};
// The memory-infra service implements this interface. There is one instance for
// the whole system. The coordinator maintains a list of registered client
// processes and polls them whenever a global dump is required.
interface Coordinator {
// Registers a client process.
RegisterClientProcess(ClientProcess client_process, ProcessType process_type);
// Broadcasts a dump request to all registered client processes and returns a
// global dump which includes allocator dumps specified in |allocator_dump_names|.
// For example, given an allocator dump name such as "malloc" or "cc/resource_memory",
// this method returns all information corresponding to this name including numeric
// entries which contain fields such as "size" and "effective_size".
RequestGlobalMemoryDump(DumpType dump_type,
LevelOfDetail level_of_detail,
array<string> allocator_dump_names) =>
(bool success, GlobalMemoryDump? global_memory_dump);
// Sends a dump request to the client process given by the specified pid and
// returns a summarized dump back or null if there was a failure.
RequestGlobalMemoryDumpForPid(mojo.common.mojom.ProcessId pid) =>
(bool success, GlobalMemoryDump? global_memory_dump);
// Broadcasts a dump request to all registered client processes and injects the
// dump in the trace buffer (if tracing is enabled).
RequestGlobalMemoryDumpAndAppendToTrace(DumpType dump_type,
LevelOfDetail level_of_detail) =>
(bool success, uint64 dump_id);
};
// Used by the Chrome heap profiler
interface HeapProfilerHelper {
// Broadcasts a RequestOSMemoryDump-only request for all registered client
// processes, retrieves only their memory maps and returns them in the field
// |global_memory_dump.process_dumps.os_dump.memory_maps_for_heap_profiler|.
GetVmRegionsForHeapProfiler() =>
(bool success, GlobalMemoryDump? global_memory_dump);
};