StorPortEtwEvent4 function

The StorPortEtwEvent4 publishes an Event Tracing for Windows (ETW) event to a storage trace channel. The miniport can log four general purpose ETW parameters. The ETW parameters are expressed as four name-value pairs.

Syntax

ULONG StorPortEtwEvent4(
  PVOID                                                        HwDeviceExtension,
  PSTOR_ADDRESS                                                Address,
  ULONG                                                        EventId,
  PWSTR                                                        EventDescription,
  ULONGLONG                                                    EventKeywords,
  STORPORT_ETW_LEVEL                                           EventLevel,
  STORPORT_ETW_EVENT_OPCODE                                    EventOpcode,
  PSCSI_REQUEST_BLOCK                                          Srb,
  _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter1Name,
  ULONGLONG                                                    Parameter1Value,
  _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter2Name,
  ULONGLONG                                                    Parameter2Value,
  _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter3Name,
  ULONGLONG                                                    Parameter3Value,
  _In_reads_or_z_opt_(STORPORT_ETW_MAX_PARAM_NAME_LENGTH)PWSTR Parameter4Name,
  ULONGLONG                                                    Parameter4Value
);

Parameters

HwDeviceExtension

A pointer to the hardware device extension for the host bus adapter (HBA).

Address

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

EventId

A miniport defined identifier for the ETW event.

EventDescription

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

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.

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.

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.

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.

Parameter1Name

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

Parameter1Value

The value for parameter 1.

Parameter2Name

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

Parameter2Value

The value for parameter 2.

Parameter3Name

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

Parameter3Value

The value for parameter 3.

Parameter4Name

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

Parameter4Value

The value for parameter 4.

Return Value

StorPortEtwEvent4 returns one of the following status codes:

Return code Description
STOR_STATUS_SUCCESS
The event published successfully storage ETW channel.
STOR_STATUS_NOT_IMPLEMENTED
Tracing is not enabled for storage events.
STOR_STATUS_INVALID_PARAMETER
The HwDeviceExtension parameter is NULL. -or- EventDescription is NULL. -or- EventDescription is greater than the maximum name length. -or- An ETW parameter name is greater than the maximum name length.

Remarks

If any parameter is not named, ParameterXName = NULL, the routine will set the corresponding parameter value to 0.

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

Requirements

   
Windows version Available in starting with Windows 8.1.
Target Platform Universal
Header storport.h (include Storport.h)
IRQL "<= DISPATCH_LEVEL"

See Also

StorPortEtwEvent2

StorPortEtwEvent8