StorPortEtwLogByteStream function (storport.h)

Article
10/21/2021

StorPortEtwLogByteStream logs an Event Tracing for Windows (ETW) event with a general purpose byte stream parameter to the specified channel.

Syntax

ULONG StorPortEtwLogByteStream(
  [in]           PVOID                      HwDeviceExtension,
  [in, optional] PSTOR_ADDRESS              Address,
  [in]           STORPORT_ETW_EVENT_CHANNEL EventChannel,
  [in]           ULONG                      EventId,
  [in]           PWSTR                      EventDescription,
  [in]           ULONGLONG                  EventKeywords,
  [in]           STORPORT_ETW_LEVEL         EventLevel,
  [in]           STORPORT_ETW_EVENT_OPCODE  EventOpcode,
  [in]           USHORT                     DataLength,
  [in]           PUCHAR                     Data
);

Parameters

[in] HwDeviceExtension

A pointer to the miniport's device extension.

[in, optional] Address

The storage unit device address. This parameter is NULL for adapter devices.

[in] EventChannel

A STORPORT_ETW_EVENT_CHANNEL value that identifies the ETW channel in which to log the event.

[in] EventId

A miniport-defined event ID that uniquely identifies the event.

[in] EventDescription

A short string describing the event. EventDescription is required and must be <= STORPORT_ETW_MAX_DESCRIPTION_LENGTH characters, not including the NULL terminator.

[in] EventKeywords

Keyword flags for event categorization. Set to 0 if no keyword is desired. The keywords are a bitwise OR combination of the following.

Value	Meaning
STORPORT_ETW_EVENT_KEYWORD_IO	The event is related to device IO operations.
STORPORT_ETW_EVENT_KEYWORD_PERFORMANCE	The event is performance related.
STORPORT_ETW_EVENT_KEYWORD_POWER	The event is related to device power.
STORPORT_ETW_EVENT_KEYWORD_ENUMERATION	The event is related to device enumeration.

[in] EventLevel

The event level. This value can indicate the importance or severity of the event. This is one of the following values.

Value	Meaning
StorportEtwLevelLogAlways	Log the event unconditionally. The event is logged regardless of any filters set.
StorportEtwLevelCritical	Critical level event.
StorportEtwLevelError	Error level event.
StorportEtwLevelWarning	Warning level event.
StorportEtwLevelInformational	Informational event.
StorportEtwLevelVerbose	Verbose event information provided.

[in] EventOpcode

The operational nature of the event. This is one of the following values.

Value	Meaning
StorportEtwEventOpcodeInfo	General informational event.
StorportEtwEventOpcodeStart	Device or unit was starting.
StorportEtwEventOpcodeStop	Device or unit was stopping. The event corresponds to the last unpaired start event.
StorportEtwEventOpcodeDC_Start	A data collection starting event. These are rundown event types.
StorportEtwEventOpcodeDC_Stop	A data collection stopping event. These are rundown event types.
StorportEtwEventOpcodeExtension	An extension event.
StorportEtwEventOpcodeReply	A reply event.
StorportEtwEventOpcodeResume	Device or unit was resuming after suspend.
StorportEtwEventOpcodeSuspend	Device or unit is suspended pending completion of another operation.
StorportEtwEventOpcodeReceive	Transfer of activity is received from another component.

[in] DataLength

Length, in bytes, of the byte stream that Data points to, where 1 <= DataLength <= STORPORT_ETW_MAX_BYTE_STREAM_LENGTH.

[in] Data

Pointer to the miniport's custom ETW byte stream.

Return value

StorPortEtwLogByteStream returns one of the following status codes:

Return code	Description
STOR_STATUS_SUCCESS	The event was successfully logged to the specified ETW channel.
STOR_STATUS_INVALID_PARAMETER	A parameter is invalid. For example, HwDeviceExtension, EventDescription, or Data are NULL, DataLength is greater than the maximum name length, EventChannel is an invalid value.
STOR_STATUS_UNSUCCESSFUL	Returned for other internal reasons.

Remarks

A miniport can call StorPortEtwLogByteStream to log an ETW event to a specific channel with a general purpose byte stream parameter.

StorPortEtwLogByteStream is useful when a miniport needs to log context beyond that allowed in StorPortEtwEvent2, StorPortEtwEvent4, or StorPortEtwEvent8. For instance, a miniport can log its internal data structure as a byte stream that can then be used for diagnostic purposes when issues get reported.

Requirements

Requirement	Value
Minimum supported server	Windows Server 2022
Header	storport.h