DoTraceMessage를 사용자 지정할 수 있나요?

아티클
02/07/2024

예, 고유한 버전의 DoTraceMessage 매크로를 작성할 수 있습니다. DoTraceMessage는 추적 메시지를 생성합니다.

TraceDrv 샘플 드라이버는 이 항목에 설명된 메서드의 예를 제공합니다. TraceDrv 는 GitHub의 Windows 드라이버 샘플 리포지토리에서 사용할 수 있습니다.

DoTraceMessage: 기본 버전

기본적으로 DoTraceMessage 매크로의 형식은 다음과 같습니다.

DoTraceMessage(Flag,"Message",MessageVariables...);

이 기본 버전에서 플래그 는 메시지가 생성되는 조건인 추적 플래그를 나타냅니다. MessageVariables 에는 드라이버가 정의하고 추적 메시지에 표시되는 변수의 쉼표로 구분된 목록이 포함되어 있습니다. MessageVariables 변수는 printf 요소를 사용하여 형식이 지정됩니다. WPP 전처리기는 DoTraceMessage 매크로에서 컴파일러 지시문을 만듭니다. 이 매크로는 커널 모드 드라이버 또는 사용자 모드 애플리케이션과 같이 추적 공급자에 대해 생성된 PDB 파일에 메시지 정의 정보 및 서식 정보를 추가합니다.

DoTraceMessage 매크로는 논리적으로 다음으로 확장됩니다.

PRE macro // If defined
If (WPP_CHECK_INIT && Flag is enabled) {
 ....Call WmiTraceMessage;
}
POST macro // If defined

다음 코드 예제를 생각해보세요.

DoTraceMessage(ERROR, "IOCTL = %d", ControlCode);

이 호출은 ERROR 플래그를 사용할 때 추적 메시지를 생성합니다. 메시지는 "IOCTL=%d"이고 MessageVariables 는 ControlCode 값입니다.

사전 로깅 및 POST 로깅 매크로가 정의된 경우 매크로도 확장됩니다. PRE 매크로 및 POST 매크로는 Microsoft Windows 2000 이상 운영 체제에서 지원됩니다. 매크로를 사용하려면 WDK를 사용하여 드라이버를 빌드해야 합니다. 이전 버전의 Windows DDK(드라이버 개발 키트)를 사용하여 드라이버를 빌드하는 경우 PRE 및 POST 기능을 사용할 수 없으며 매크로는 추적 문의 일부로 실행되지 않습니다. 이전 버전의 Windows DDK를 사용하여 드라이버를 빌드하면 빌드 중단이 발생하지 않을 수 있지만 코드는 예상대로 작동하지 않습니다.

DoTraceMessage: 일반 형식

다음은 유효한 추적 메시지 함수의 일반적인 형식입니다.

FunctionName(Conditions...,"Message",MessageVariables...);

메시지 앞에 나타나는 매개 변수는 조건으로 해석됩니다. 메시지 다음에 나타나는 매개 변수는 메시지 변수로 해석됩니다.

조건은 쉼표로 구분된 값 목록입니다. 추적 메시지는 모든 조건이 true인 경우에만 생성됩니다. 코드에서 지원되는 모든 조건을 지정할 수 있습니다.

예: MyTrace

다음은 추적 함수의 샘플입니다. 다음은 추적 메시지를 생성하는 공급자의 하위 구성 요소 및 추적 수준에 대한 조건을 추가하는 예제입니다.

MyDoTrace(Level, Flag, Subcomponent,"Message",MessageVariables...);

예를 들면 다음과 같습니다.

MyDoTrace(TRACE_LEVEL_ERROR, VERBOSE, Network,"IOCTL = %d", ControlCode);

추적 수준은 WDK의 Include 하위 디렉터리에 있는 공용 헤더 파일인 Evntrace.h에 정의된 표준 수준입니다.

#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(for example, Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9

사용자 지정 추적 함수를 만드는 방법

사용자 지정 추적 함수를 만들려면 다음 단계를 수행합니다.

DoTraceMessage 매크로를 지원하는 다른 버전의 매크로를 작성합니다.
WPP 전처리기를 호출하는 RUN_WPP 문에 -func 매개 변수를 추가합니다.

사용자 지정 매크로 작성

추적 메시지(메시지 앞에 나타나는 매개 변수)의 조건을 변경하는 사용자 지정 추적 함수를 만들려면 추적 함수, WPP_LEVEL_ENABLED 및 WPP_LEVEL_LOGGER 지원하는 매크로의 대체 버전을 작성해야 합니다.

WPP_LEVEL_ENABLED(Flags) 는 지정된 플래그 값으로 로깅을 사용할 수 있는지 여부를 결정합니다. TRUE 또는 FALSE를 반환합니다.
WPP_LEVEL_LOGGER(Flags) 는 공급자가 사용하도록 설정된 추적 세션을 찾아 추적 세션에 대한 핸들을 반환합니다.

예를 들어 플래그 외에도 추적 수준을 조건으로 포함하려는 경우 추적 수준을 포함하는 새 WPP_LEVEL_ENABLED 매크로를 정의합니다. 다음 코드 예제와 같이 기본 매크로에서 새 매크로의 정의를 기반으로 할 수 있습니다.

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >=lvl

일반적으로 WPP_LEVEL_LOGGER 매크로는 영향을 받지 않습니다. 이러한 경우 새 매크로를 기본 매크로로 정의할 수 있습니다. 예를 들면 다음과 같습니다.

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) WPP_LEVEL_LOGGER(flags)

그러나 어떤 경우에는 LOGGER 매크로를 변경해야 합니다. 예를 들어 플래그가 아닌 추적 수준에만 의존하는 추적 함수를 작성할 수 있습니다.

다음 코드 예제에서는 매크로의 flags 값이 더미 값으로 바뀝니다. 컨트롤 GUID 정의를 선언할 때 플래그가 정의되지 않습니다.

#define WPP_CONTROL_GUIDS \
   WPP_DEFINE_CONTROL_GUID(CtlGuid,(a044090f,3d9d,48cf,b7ee,9fb114702dc1),  \
        WPP_DEFINE_BIT(DUMMY))

#define WPP_LEVEL_LOGGER(lvl) (WPP_CONTROL(WPP_BIT_ ## DUMMY).Logger)

WPP에 함수 추가

WPP에 사용자 지정 추적 함수를 추가하려면 다음 코드 예제와 같이 함수 선언을 사용하여 RUN_WPP 문에 -func 매개 변수를 추가합니다.

RUN_WPP=$(SOURCES) -km -func:DoTraceLevelMessage(LEVEL,FLAGS,MSG,...)

참고 사용자 모드 애플리케이션 또는 DLL(동적 연결 라이브러리)에 대한 RUN_WPP 지시문에서 -km 스위치를 지정해서는 안 됩니다.

RUN_WPP 대한 선택적 매개 변수의 전체 목록은 WPP 전처리기를 참조하세요.

다음을 통해 공유