Función TraceConfigureLastBranchRecord (evntrace.h)

Configura un seguimiento de eventos para la sesión de Windows (ETW) para generar eventos de seguimiento del último registro de rama (LBR) en respuesta a los eventos desencadenadores especificados.

Syntax

ULONG TraceConfigureLastBranchRecord(
  CONTROLTRACE_ID         TraceId,
  TRACE_LBR_CONFIGURATION LbrConfiguration,
  CLASSIC_EVENT_ID const  *Events,
  ULONG                   EventCount
);

Parámetros

TraceId

Un CONTROLTRACE_ID que representa un identificador de la sesión ETW que se va a configurar. Este es el identificador de sesión devuelto por StartTrace.

LbrConfiguration

Una o varias marcas de TRACE_LBR_CONFIGURATION que controlan cómo se recopilan los registros LBR. Normalmente, estas marcas son opcionales y se pueden usar para filtrar las ramas registradas (por ejemplo, ramas de kernel frente a ramas de usuario o tipos de rama específicos). En algunas arquitecturas, es posible que se requiera una marca para que la configuración se realice correctamente (por ejemplo, EVNTRACE_LBR_SAMPLED en dispositivos ARM64 que solo admiten SPE y no BRBE).

typedef enum EVNTRACE_LBR_FLAGS
{
  EVNTRACE_LBR_FILTER_NONE        = 0x0,
  EVNTRACE_LBR_FILTER_KERNEL        = 0x1,
  EVNTRACE_LBR_FILTER_USER          = 0x2,
  EVNTRACE_LBR_FILTER_JCC           = 0x4,
  EVNTRACE_LBR_FILTER_NEAR_REL_CALL = 0x8,
  EVNTRACE_LBR_FILTER_NEAR_IND_CALL = 0x10,
  EVNTRACE_LBR_FILTER_NEAR_RET      = 0x20,
  EVNTRACE_LBR_FILTER_NEAR_IND_JMP  = 0x40,
  EVNTRACE_LBR_FILTER_NEAR_REL_JMP  = 0x80,
  EVNTRACE_LBR_FILTER_FAR_BRANCH    = 0x100,
  EVNTRACE_LBR_CALLSTACK_ENABLE     = 0x200,
  EVNTRACE_LBR_SAMPLED              = 0x400 // ARM64 only
} TRACE_LBR_CONFIGURATION;

Events

Puntero a una matriz de estructuras de CLASSIC_EVENT_ID que identifican los eventos que desencadenan la colección LBR. Cada elemento especifica un GUID del proveedor de eventos y un tipo de evento clásico. Los eventos desencadenadores especificados también deben estar habilitados para la sesión (por ejemplo, a través de marcas del registrador del sistema StartTrace o EnableTraceEx2); De lo contrario, no se generarán los eventos LBR correspondientes.

EventCount

Número de elementos de la matriz Events. Si EventCount es cero, la función borra la lista de eventos desencadenadores y deshabilita la colección LBR para la sesión. Si EventCount es mayor que cero, la función habilita la colección LBR para la sesión y configura hasta EVNTRACE_MAX_LBR_EVENTS desencadenadores de eventos.

Valor devuelto

Devuelve ERROR_SUCCESS si la función se realiza correctamente. De lo contrario, devuelve un código de error win32.

Remarks

Cuando la colección LBR está habilitada, ETW emite un evento LBR correlacionado cada vez que se registra uno de los eventos desencadenadores configurados en la sesión. El proveedor de LBR emite el evento LBR (GUID 99134383-5248-43fc-834b-529454e75df3) con 0x20 de código de operación. La carga del evento LBR es una estructura de LBR_TRACE_EVENT_DATA y la marca de tiempo del evento LBR coincide con la marca de tiempo del evento desencadenador.

Por ejemplo, para recopilar LBR en interrupciones de PMC del proveedor de seguimiento del sistema PerfInfo, especifique un CLASSIC_EVENT_ID con el GUID del proveedor ce1dbfb4-137e-4da6-87b0-3f59aa102cbc y el tipo 0x2f (PERFINFO_LOG_TYPE_PMC_INTERRUPT). Durante la reproducción de seguimiento (por ejemplo, mediante ProcessTrace), el evento desencadenador y su evento LBR correlacionado tienen marcas de tiempo idénticas.

Los eventos desencadenadores deben estar habilitados para la sesión y no se pueden configurar más de EVNTRACE_MAX_LBR_EVENTS desencadenadores a la vez. Al usar LBR con la generación de perfiles de PMC o el registrador del sistema, el autor de la llamada normalmente debe ejecutarse con privilegios elevados y contener seSystemProfilePrivilege (SE_SYSTEM_PROFILE_NAME).

Para enriquecer el seguimiento resultante con metadatos adicionales, puede procesar después de procesar la salida mediante CreateMergedTraceFile para agregar datos extendidos, como EVENT_TRACE_MERGE_EXTENDED_DATA_IMAGEID. Esto requiere KernelTraceControl.dll del Windows Performance Toolkit (WPT). Como alternativa, puede usar xperf -merge, que también proporciona WPT.

Datos del evento LBR

Los eventos LBR tienen una carga que comienza con un encabezado LBR_TRACE_EVENT_DATA , seguido de uno o varios registros ETW_LBR_ENTRY . Cada entrada identifica un borde de rama de FromAddress a ToAddress y LBR_INFO campo Información. El número de entradas se determina a partir del tamaño de carga del evento.

#pragma pack(push, 1)

typedef struct ETW_LBR_ENTRY
{
  PVOID FromAddress;
  PVOID ToAddress;
  PVOID Information;
} ETW_LBR_ENTRY, *PETW_LBR_ENTRY;

typedef struct LBR_TRACE_EVENT_DATA
{
  ULONGLONG TimeStamp;
  ULONG ProcessId;
  ULONG ThreadId;
  ULONG Options;
  ULONG Unused;
  ETW_LBR_ENTRY Entries[1]; // variable-length
} LBR_TRACE_EVENT_DATA, *PLBR_TRACE_EVENT_DATA;

#pragma pack(pop)

Examples

En el ejemplo siguiente se inicia una sesión del registrador del sistema, se configura la colección LBR en los eventos de interrupción de PMC de PerfInfo mediante TraceConfigureLastBranchRecord y, a continuación, se habilita la generación de perfiles de PMC para la sesión.

#include <windows.h>
#include <evntrace.h>

static const GUID PerfinfoGuid =
{ 0xce1dbfb4, 0x137e, 0x4da6, { 0x87, 0xb0, 0x3f, 0x59, 0xaa, 0x10, 0x2c, 0xbc } };

typedef struct _MyEventTraceProperties_t
{
  EVENT_TRACE_PROPERTIES Properties;
  WCHAR LoggerName[MAX_PATH];
  WCHAR LogFileName[MAX_PATH];
} MyEventTraceProperties_t;

typedef struct _PERFINFO_GROUPMASK
{
  ULONG Masks[8];
} PERFINFO_GROUPMASK;

BOOL EnableSystemProfilePrivilege();

int main()
{
  CONTROLTRACE_ID traceHandle = 0;
  ULONG status = ERROR_SUCCESS;
  MyEventTraceProperties_t props = {};

  wcscpy_s(props.LoggerName, MAX_PATH, L"LbrLogger");
  wcscpy_s(props.LogFileName, MAX_PATH, L"LbrProfile.etl");

  props.Properties.Wnode.BufferSize = sizeof(props);
  props.Properties.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
  props.Properties.LogFileMode = EVENT_TRACE_FILE_MODE_SEQUENTIAL | EVENT_TRACE_SYSTEM_LOGGER_MODE;
  props.Properties.EnableFlags = EVENT_TRACE_FLAG_PROCESS | EVENT_TRACE_FLAG_THREAD | EVENT_TRACE_FLAG_IMAGE_LOAD;
  props.Properties.LoggerNameOffset = offsetof(MyEventTraceProperties_t, LoggerName);
  props.Properties.LogFileNameOffset = offsetof(MyEventTraceProperties_t, LogFileName);

  if (!EnableSystemProfilePrivilege())
    return 1;

  // Specify the PMC event to profile on and configure its interval.
  // This preferably needs to be done before starting a trace.
  TRACE_PROFILE_INTERVAL profile = {};
  profile.Source = 6;     // ProfileBranchInstructions (see: wpr -pmcsources)
  profile.Interval = 65536;

  status = TraceSetInformation(NULL, TraceProfileSourceConfigInfo, &profile.Source, sizeof(ULONG));
  if (status != ERROR_SUCCESS) return 1;

  status = TraceSetInformation(NULL, TraceSampledProfileIntervalInfo, &profile, sizeof(profile));
  if (status != ERROR_SUCCESS) return 1;

  status = StartTraceW(&traceHandle, props.LoggerName, &props.Properties);
  if (status != ERROR_SUCCESS) return 1;

  // Configure LBR to trigger on PerfInfo PMC interrupt (type 0x2f).
  CLASSIC_EVENT_ID profileEvent = {};
  profileEvent.EventGuid = PerfinfoGuid;
  profileEvent.Type = 0x2f; // PERFINFO_LOG_TYPE_PMC_INTERRUPT

  status = TraceConfigureLastBranchRecord(
    traceHandle,
    TRACE_LBR_CONFIGURATION_NONE, // no filters
    &profileEvent,
    1);
  if (status != ERROR_SUCCESS) goto Stop;

  // Start PMC profiling and associate it with this trace.
  // This is done by setting the second mask to the PMC_PROFILE mask.
  PERFINFO_GROUPMASK pmcMasks = {};
  pmcMasks.Masks[1] = 0x00000400; // Mask of PERF_PMC_PROFILE
  status = TraceSetInformation(traceHandle, TraceSystemTraceEnableFlagsInfo, &pmcMasks, sizeof(pmcMasks));

Stop:
  ControlTraceW(traceHandle, NULL, &props.Properties, EVENT_TRACE_CONTROL_STOP);
  return (status == ERROR_SUCCESS) ? 0 : 1;
}

Requirements

Consulte también

• StartTrace
• ControlTrace
• TraceSetInformation
• CLASSIC_EVENT_ID