Geoff Chappell, Software Analyst
PLACEHOLDER FOR WORK THAT MAY NEVER BE DONE - PREVIEW ONLY
When given EtwStartLoggerCode (1) as its FunctionCode argument, the NtTraceControl function starts a tracing session, known informally as a logger. This note deals only with the function’s behaviour that is particular to this function code. The function’s general behaviour is here taken as assumed knowledge.
Well-behaved user-mode software does not call NtTraceControl. The documented user-mode API for reaching this functionality is StartTrace. This is a shorthand for two functions, StartTraceA and StartTraceW, being ANSI and Unicode variants respectively. Both are exported by name from ADVAPI32 in version 5.0 and higher. In version 5.2 only, these functions are merely forwards to the undocumented NTDLL exports EtwStartTraceA and EtwStartTraceW. Implementation returns to ADVAPI32 in version 6.0. Then, in version 6.2 and higher, the ADVAPI32 implementations are stubs that redirect to KERNELBASE.DLL in version 6.2 but to SECHOST.DLL in version 6.3 and higher. For StartTraceW only, this redirection imports through the API Set api-ms-win-eventing-controller-l1-1-0.dll.
The StartTrace function predates NtTraceControl. In versions before 6.0, it reaches the kernel by Device I/O Control through the WMI support device. However important this earlier functionality may have been at the time, and may be still for historians of how and why Microsoft kept so much of Event Tracing for Windows (ETW) to itself for so long, it is not the concern of this note.
Kernel-mode software also does not call NtTraceControl to start a tracing session.
A WMI_LOGGER_INFORMATION structure is expected to begin the input and is produced as the function’s successful output. If either the input or output buffer is too small for this structure, including because a user-mode request gives NULL for either buffer’s address, the function returns STATUS_INVALID_BUFFER_SIZE. If a kernel-mode request provides no input, the returned error code is STATUS_INVALID_PARAMETER.
The expected structure begins with a WNODE_HEADER. Within this, the BufferSize tells how many bytes of data this header is the first part of. If this is too small even for the fixed-size WMI_LOGGER_INFORMATION, the function returns STATUS_INVALID_BUFFER_SIZE. The Flags in the WNODE_HEADER tell of the header’s interpretation and purpose. Use in Event Tracing for Windows (ETW) requires WNODE_FLAG_TRACED_GUID (0x00020000). If this is not set, the function returns STATUS_INVALID_PARAMETER. If BufferSize in the header is too large for the input buffer, the function returns STATUS_INVALID_BUFFER_SIZE.
The key to intepreting the many properties that can be specified in the WMI_LOGGER_INFORMATION is the set of bit flags that make the LogFileMode. Some flags are ignored. Very many combinations are invalid and cause the function to return STATUS_INVALID_PARAMETER. Some flags require another or are inconsistent with another, but the resolution is to proceed as if the other is set or clear.
TO BE DONE?