StorPortEtwEvent8 function (storport.h)

Article
10/21/2021

StorPortEtwEvent8 logs an Event Tracing for Windows (ETW) event with eight general-purpose ETW parameters to a storage trace channel.

Syntax

ULONG StorPortEtwEvent8(
  [in]           PVOID                                                        HwDeviceExtension,
  [in, optional] PSTOR_ADDRESS                                                Address,
  [in]           ULONG                                                        EventId,
  [in]           PWSTR                                                        EventDescription,
  [in]           ULONGLONG                                                    EventKeywords,
  [in]           STORPORT_ETW_LEVEL                                           EventLevel,
  [in]           STORPORT_ETW_EVENT_OPCODE                                    EventOpcode,
  [in, optional] PSCSI_REQUEST_BLOCK                                          Srb,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter1Name,
  [in]           ULONGLONG                                                    Parameter1Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter2Name,
  [in]           ULONGLONG                                                    Parameter2Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter3Name,
  [in]           ULONGLONG                                                    Parameter3Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter4Name,
  [in]           ULONGLONG                                                    Parameter4Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter5Name,
  [in]           ULONGLONG                                                    Parameter5Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter6Name,
  [in]           ULONGLONG                                                    Parameter6Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter7Name,
  [in]           ULONGLONG                                                    Parameter7Value,
  [in, optional] _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter8Name,
  [in]           ULONGLONG                                                    Parameter8Value
);

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] EventId

A miniport-defined identifier for the ETW event.

[in] EventDescription

The description text for the event. This text string must be <= STORPORT_ETW_MAX_DESCRIPTION_LENGTH.

[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, optional] Srb

A pointer to the SRB associated with the logged event. If this parameter contains a valid SRB, this SRB pointer and the associated SRB pointer are logged.

[in, optional] Parameter1Name

A description of the meaning of Parameter1Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter1Value

The value for parameter 1.

[in, optional] Parameter2Name

A description of the meaning of Parameter2Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter2Value

The value for parameter 2.

[in, optional] Parameter3Name

A description of the meaning of Parameter3Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter3Value

The value for parameter 3.

[in, optional] Parameter4Name

A description of the meaning of Parameter4Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter4Value

The value for parameter 4.

[in, optional] Parameter5Name

A description of the meaning of Parameter5Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter5Value

The value for parameter 5.

[in, optional] Parameter6Name

A description of the meaning of Parameter6Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter6Value

The value for parameter 6.

[in, optional] Parameter7Name

A description of the meaning of Parameter7Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter7Value

The value for parameter 7.

[in, optional] Parameter8Name

A description of the meaning of Parameter8Value. This parameter name string must be <= STORPORT_ETW_MAX_PARAM_NAME_LENGTH.

[in] Parameter8Value

The value for parameter 8.

Return value

StorPortEtwEvent8 returns one of the following status codes:

Return code	Description
STOR_STATUS_SUCCESS	The event was successfully logged.
STOR_STATUS_NOT_IMPLEMENTED	Tracing is not enabled for storage events.
STOR_STATUS_INVALID_PARAMETER	One of the parameters is invalid. For example, HwDeviceExtension or EventDescription are NULL, EventDescription is greater than the maximum name length, or an ETW parameter name is greater than the maximum name length.

Remarks

A miniport can call StorPortEtwEvent8 to log eight general-purpose ETW parameters. The ETW parameters are expressed as eight name-value pairs. If a parameter is not named (ParameterXName = NULL), the routine will set the corresponding parameter value to 0.

Events generated from StorPort miniport drivers are logged to the "Microsoft-Windows-Storage-Storport/Diagnose" ETW channel.

Requirements

Requirement	Value
Minimum supported client	Windows 8.1
Target Platform	Universal
Header	storport.h (include Storport.h)
IRQL	<= DISPATCH_LEVEL