syzygy/trace/rpc/logger_rpc.idl

// Copyright 2012 Google Inc. All Rights Reserved.
//
// 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.
//

const wchar_t* const kLoggerRpcProtocol = L"ncalrpc";
const wchar_t* const kLoggerRpcEndpointRoot = L"syzygy-logger";

typedef struct ExecutionContext {
#ifndef _WIN64
  // Integer registers.
  unsigned long edi;
  unsigned long esi;
  unsigned long ebx;
  unsigned long edx;
  unsigned long ecx;
  unsigned long eax;

  // Control registers.
  unsigned long ebp;
  unsigned long eip;
  unsigned long seg_cs;
  unsigned long eflags;
  unsigned long esp;
  unsigned long seg_ss;
#else
  unsigned long long rdi;
  unsigned long long rsi;
  unsigned long long rbx;
  unsigned long long rdx;
  unsigned long long rcx;
  unsigned long long rax;

  unsigned long long rbp;
  unsigned long long rip;
  unsigned long long rsp;
  unsigned long eflags;
  unsigned long seg_cs;
  unsigned long seg_ss;
#endif
} ExecutionContext;

// Defines the Logger's RPC interface.
[
    uuid(2851769C-7E7D-477C-8A19-622001F9A84E),
    version(1.0)
]
interface Logger {
  // Write some text to the log.
  // @param text The string to be logged.
  boolean Write([in] handle_t binding, [in, string] const char* text);

  // Write a message and stack trace to the log.
  //
  // The log server will use the provided execution @p context and symbol
  // information to resolve the most accurate textual stack trace possible.
  //
  // The context must remain valid throughout this call. This means that the
  // context must either belong to the calling thread (which will block on this
  // call) or else the thread whose execution context is provided should be
  // blocked or suspended
  //
  // @param text The string to be logged.
  // @param context The execution context from which to derive a stack trace.
  boolean WriteWithContext(
      [in] handle_t binding,
      [in, string] const char* text,
      [in] const ExecutionContext* context);

  // Write a message and stack trace to the log. The stack trace must have
  // been captured by the caller already. See RtlCaptureStackBacktrace for
  // fast, but only approximate, in-proc stack capture.
  // @param text The string to be logged.
  // @param trace A pointer to the stack trace capture.
  // @param trace_size The size (in bytes) if the stack trace capture.
  boolean WriteWithTrace(
      [in] handle_t binding,
      [in, string] const char* text,
      [in, size_is(trace_length)] const unsigned __int3264 trace_data[*],
      [in] long trace_length);

  // Generate a minidump for the calling process.
  // @param thread_id the ID of the calling thread.
  // @param exception A pointer to an EXCEPTION_POINTERS record describing the
  //     reason for the minidump, or NULL, cast to an unsigned long. The logger
  //     peek into the calling process to read the exception pointers.
  // @param protobuf The protobuf to include in the minidump.
  // @param protobuf_length The length of the protobuf.
  // @param memory_ranges_base_addresses An array containing the base addresses
  //     of the memory ranges to include in the protobuf.
  // @param memory_ranges_lengths An array containing the size of these memory
  //     ranges.
  // @param memory_ranges_count The number of memory ranges to report.
  // @returns true on success, false otherwise.
  boolean SaveMinidumpWithProtobufAndMemoryRanges(
      [in] handle_t binding,
      [in] unsigned long thread_id,
      [in] unsigned __int64 exception,
      [in, size_is(protobuf_length)] const byte protobuf[*],
      [in] unsigned long protobuf_length,
      [in, size_is(memory_ranges_count)]
          const unsigned long memory_ranges_base_addresses[*],
      [in, size_is(memory_ranges_count)] const unsigned long
          memory_ranges_lengths[*],
      [in] unsigned long memory_ranges_count);
}

// Defines the Logger's RPC Control interface.
// TODO(rogerm): Move this to it's own IDL file and endpoint.
[
    uuid(6514F04C-4BD5-48AE-BD2D-8E071DA29752),
    version(1.0)
]
interface LoggerControl {
  // Retrieves the process ID of the process that owns the specified logging
  // service.
  unsigned long GetProcessId([in] handle_t binding);

  // Request a shutdown of the logging service.
  boolean Stop([in] handle_t binding);
}