DevHlp SysTrace

The DevHlp_RAS, DevHlp_SysTrace and DevHlp_AddTraceEvent function provides a service for device drivers to add information to the System Trace buffer.

Note

DevHlp_AddTraceEvent, DevHlp_SysTrace and DevHelp_RAS are the same services.

Syntax

C

DevHlp_SysTrace ( USHORT Major, USHORT Minor, USHORT Size, PBYTE Data)

or

DevHelp_RAS (USHORT  Major, USHORT  Minor, USHORT  Size, PBYTE   Data)

Assembler

Calling Sequence in Assembler

MOV   AX, MajorCode           ; major trace event code (240-255)
MOV   BX, Length              ; length of data area (0-512 bytes)
MOV   CX, MinorCode           ; minor trace event code (0-255)

LDS   SI, Data                ; pointer to trace data

MOV   DL, 28H                 ; DevHlp_RAS function code

CALL  [Device_Help]          ; invoke device helper

Parameters

C

Major (USHORT) - input

Major trace event code (240-255). The major code to be placed in the trace buffer. Only the low order byte is used. The high order byte should be 0 for future compatibility reasons, but no error checking of the high order byte is performed.

Minor (USHORT) - input

Minor trace event code (0-255). The minor code to be placed in the trace buffer. This code identifies the specific trace event. Only the low order byte is used. The high order byte should be 0 for future compatibility reasons, but no error checking of the high order byte is performed.

Size (USHORT) - input

Length of the variable length area to be recorded (0-512). The length of the area pointed to by the address parameter. If a length greater than 512 is specified, only 512 bytes will be recorded. If a length of 0 is specified, the address parameter will not be used; however, a dummy doubleword must be pushed on the stack so that all calls use the same stack space.

Data (PBYTE) - input

Pointer to the area to be traced (address parameter). The address of the variable length data area which contains additional information that the system trace function will add to the trace buffer. If a length of 0 is specified, the address will not be used, but a value must still be added to the stack.

Assembler

MOV   AX,MajorCode           ; major trace event code (240-255)
MOV   BX,Length              ; length of data area (0-512 bytes)
MOV   CX,MinorCode           ; minor trace event code (0-255)

LDS   SI,Data                ; pointer to trace data

MOV   DL,28H                 ; DevHlp_RAS function code

Return Code

C

• Success indicator 0.

Possible errors

• Data not traced, e.g., major event code is not currently selected for tracing.

An example of when data would not be traced is if the major event code is not currently selected for tracing.

Assembler

   If CF = 0
       Trace record placed in trace buffer
   Else
       Data not traced

Possible errors:

• Tracing suspended
• Minor code not being traced
• PID not being traced
• Trace overrun

Remarks

The trace facility maintains an array of 32 bytes (256 bits), in which each bit represents a major event code. This array is updated each time the user enables or disables tracing of a major event. The device driver must check this array before calling DevHlp_SysTrace or DevHlp_RAS to ensure that the major event specified is currently enabled for tracing. This array is located in the Global InfoSegAll registers are preserved.

Interrupts are disabled while the trace data is saved and then re-enabled if they were initially enabled.

DevHlp_SysTrace is synonymous with DevHlp_RAS and AddTraceEvent.

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_RAS (USHORT  Major, USHORT  Minor, USHORT  Size, PBYTE   Data);

or

#include  "dhcalls.h"

USHORT APIENTRY DevHlp_SysTrace ( USHORT Major, USHORT Minor, USHORT Size, PBYTE Datar )

16-bit MASM Example

        MOV   AX, MajorCode           ; major trace event code (240-255)
        MOV   BX, Length              ; length of data area (0-512 bytes)
        MOV   CX, MinorCode           ; minor trace event code (0-255)
        LDS   SI, pData               ; pointer to trace data
        MOV   DL, 28H                 ; DevHlp_RAS function code
        CALL  [Device_Help]          ; invoke device helper