Null-Modem Cable

Configuring Hardware for
Kernel-Mode Debugging
Windows Driver Development
Getting Start
Host
Target
Null-Modem
Cable
主講人：虞台文
Running free build OS
and kernel debugger
1
Running checked build OS
5
Content
Null-Modem Cable
?Setup
?
the Environment
?Driver Development
?Installation
?
If you do not have access to a null-modem cable,
or if you prefer to customize your hardware
wiring, the following information may be useful.
A standard, commercially available null-modem
cable has the following configuration:
–
–
–
2
Transmit Data connected to Receive Data
Receive Data connected to Transmit Data
Ground connected to Ground
6
Null-Modem Cable
Windows Driver Development
Getting Start
Setup the
Environment
Gnd
Rcv
Tx
Gnd
3
Rcv
7
Serial Ports
Basic Requirements
The default serial port for debug output
from the target computer is the highest
enumerated port (usually COM2). This can be
changed by setting the debugport option.
? Hardware
–
–
Host
Two computers
Null-Modem Cable
? Software
–
–
–
4
Tx
Target
Null-Modem
Cable
Checked/Free Build OS
DDK/SDK/Visual C++
Debugger
Running free build OS
and kernel debugger
8
Running checked build OS
Configuring Software on the
Host Computer
Serial Ports
The default serial port for debug input to the
host computer is COM1 . This can be changed
by setting the _NT_DEBUG_PORT
environment variable.
Host
Host
Target
Target
Install
Install Windbug
Windbug
Null-Modem
Cable
Running free build OS
and kernel debugger
Null-Modem
Cable
Running free build OS
and kernel debugger
Running checked build OS
9
Configuring Software on the
Target Computer (x86)
?
?
Environment Variables
The target computer must be configured to enable kernelmode debugging before any debugging can be done.
The following batch file could be used with a COM1 connection:
set
set_NT_SYMBOL_PATH
_NT_SYMBOL_PATH==d:\mysymbols
d:\mysymbols
set
set_NT_DEBUG_PORT
_NT_DEBUG_PORT ==com1
com1
set
set_NT_DEBUG_BAUD_RATE
_NT_DEBUG_BAUD_RATE==19200
19200
set
set_NT_DEBUG_LOG_FILE_OPEN
_NT_DEBUG_LOG_FILE_OPEN==d:\debuggers\logfile1.log
d:\debuggers\logfile1.log
windbg
windbg -k-k
Use the following procedure to make changes to a boot.ini
file on an x86 computer.
–
–
Start Windows Explorer. Go to <Tools | Folder Options | View> .
Make sure that Show Hidden Files and Folders is selected , and
Hide File Extension for Known File Types is cleared.
Go to the root directory of the boot volume of your computer
(on single -boot machines, usually C:\). Right-click on boot.ini.
Select Properties, and remove the read-only attribute of this
file. Click OK.
10
More Environment Variables
14
Sample Boot.ini
Setting Environment Variables
The following batch file could be used with a COM1 connection:
[boot
[bootloader]
loader]
timeout=30
timeout=30
set
set_NT_SYMBOL_PATH
_NT_SYMBOL_PATH==d:\mysymbols
d:\mysymbols
set
set_NT_DEBUG_PORT
_NT_DEBUG_PORT ==com1
com1
set
set_NT_DEBUG_BAUD_RATE
_NT_DEBUG_BAUD_RATE==19200
19200
set
set_NT_DEBUG_LOG_FILE_OPEN
_NT_DEBUG_LOG_FILE_OPEN==d:\debuggers\logfile1.log
d:\debuggers\logfile1.log
windbg
windbg -k-k
default=multi(0)disk(0)rdisk(0)partition(1)\WINNT
default=multi(0)disk(0)rdisk(0)partition(1)\WINNT
[operating
[operating systems]
systems]
multi(0)disk(0)rdisk(0)partition(1)
astdetect
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Microsoft
\WINNT="Microsoft Windows
Windows XP
XP Professional"
Professional" /f/fastdetect
multi(0)disk(0)rdisk(0)partition(3)
multi(0)disk(0)rdisk(0)partition(3)\WINDOWS="Microsoft
\WINDOWS="Microsoft Windows
Windows 98"
98"
More Samples
More Environment Variables
Parameters
11
15
Configuring Software on the
Host Computer
Symbol Files
?Two
?
major things
Setup environment variables
– Setup symbols
–
?
12
Running checked build OS
13
16
When applications, libraries, drivers, or operating
systems are linked, the linker which creates
the .exe and .dll files also creates a number of
additional files known as symbol files.
Symbol files hold a variety of data which are not
actually needed when running the binaries, but
which could be very useful in the debugging
process.
Symbol Files
?
WindowsSymbols
Typically, symbol files might contain:
–
–
–
–
–
Global variables
Local variables
Function names and the addresses of their
entry points
FPO (Frame Point Omission) data
Source-line numbers
17
21
WindowsSymbols
Set Symbol Path
Directories of a standard Windows symbol tree:
?
Directory
Contains Symbol Files for
ACM
Microsoft® Audio Compression Manager files
COM
Executable files (.com)
CPL
DLL
DRV
EXE
SCR
SYS
18
?
Control Panel programs
Dynamic-link library files (.dll)
Driver files (. drv)
–
–
Executable files (.exe)
Screen-saver files
Driver files (.sys)
For each directory in the symbol path, the
debugger will look in three directories .
For instance, if the symbol path includes the
directory c:\MyDir, and the debugger is looking
for symbol information for a DLL, the debugger
will
–
–
22
Get Symbol Files
first look in c:\MyDir\symbols\dll, then in c:\MyDir\dll,
and finally in c:\MyDir.
It will repeat this for each directory in the symbol path.
Finally, it will look in the current directory, and then the
current directory with \dll appended to it.
The debugger will append dll, exe, or sys, depending on
what binaries it is debugging.
Set Symbol Path
Example (Symbol Path):
By http://www.microsoft.com/ddk/debugging/symbols.asp
to download the following symbol packages:
set
set_NT_SYMBOL_PATH
_NT_SYMBOL_PATH==D:\Windows\XP-SP1
D:\Windows\XP-SP1
set
set_NT_DEBUG_PORT
_NT_DEBUG_PORT ==com1
com1
set
set_NT_DEBUG_BAUD_RATE
_NT_DEBUG_BAUD_RATE==19200
19200
set
set_NT_DEBUG_LOG_FILE_OPEN
_NT_DEBUG_LOG_FILE_OPEN==d:\debuggers\logfile1.log
d:\debuggers\logfile1.log
windbg
windbg -k-k
Windows XP Service Pack 1 x86 retail symbols, all languages
Windows XP Service Pack 1 x86 checked symbols, all languages
Other Methods
19
23
WindowsSymbols
?
?
20
Windows Driver Development
Getting Start
All NT -based operating systems and drivers are built in two
versions.
–
The free build (or retail build) has relatively small binaries, and
–
the checked build (or debug build) has larger binaries, with
more debugging symbols in the code itself.
Driver
Development
Each of these builds has its own symbol files. When
debugging a target on Windows, you must use the symbol
files that ‘match’the build of Windows on the target.
24
The BUILD Command
Building, Debugging, and Testing a Driver
?
Building, testing, and debugging a driver is an
iterative process that involves the following steps:
–
–
–
–
–
–
?
–
Writing the driver code, which should include debugging
routines and macros that are flagged for conditional
compilation
Building a checked version of the driver
Testing and debugging a checked version of the driver
on a checked build of each target operating system
Testing and debugging the free version of the driver on
a free build
Tuning the performance of the driver on the free build
Final testing and verification using the free build
25
Incremental build
?
build
Full build
–
build –c
Build Utility Command-Line Options
29
The Build Utility
Using Free and Checked System Builds
The Build utility requires the following files:
File
Source files
Sources file
26
Location
Typically in a subdirectory of the DDK install directry, but can be
anywhere.
Required in each directory that contains source files. it lists the source
files to be compiled and linked, and specifies values for certain macros.
Makefile file
Required in each directory that contains a sources file. It specifies
dependency relationships, compiler and linker options, and various other
build-related settings .
Dirs file
Optional file used to compile source code in multiple subdirectories
automatically. This contains macros called DIRS and OPTIONAL_DIRS
that specify the directories to open recursively and the order in which
they should be opened.
30
C:\ WINDOWS\ system32\cmd.exe /k D: \ WINDDK \2600~1.110 \bin \setenv.bat D:\WINDDK \2600~1.110 chk
The SOURCES File
Windows XP Check Build Environment
Macro
SetEnv.bat
Meaning
TARGETNAME=drivername
The name of the driver, without extension.
This will produces a drivername.sys.
TARGETPATH=obj
The root of the output path.
TARGETTYPE=DRIVER
The type for building a driver.
INCLUDES=path1;path2;…
The #include search path.
TAGETLIBS=lib1;lib2;…
The other libraries that you want to link
against.
TAGETLIBS=file1.c file2.c … The files to be compiled.
27
31
The SOURCES File
Building a Driver
?
?
?
28
The Windows DDK includes an environment for
building drivers that closely matches the build
environment used internally at Microsoft® .
This environment includes various tools useful in
developing drivers, including build utilities
(build.exe and nmake.exe), a C compiler (cl.exe),
and a linker (link.exe).
The Build utility automatically invokes nmake, the
compiler, and the linker according to the
command-line options you specify.
Example:
TARGETNAME=BusEnum
TARGETNAME=BusEnum
TARGETTYPE=DRIVER
TARGETTYPE=DRIVER
TARGETPATH=obj
TARGETPATH=obj
MSC_WARNING_LEVEL=-W3
MSC_WARNING_LEVEL=-W3 --WX
WX
NTTARGETFILE0=mofcomp
NTTARGETFILE0=mofcomp
SOURCES=
SOURCES=busenum.rc
busenum.rc \\
busenum.c
busenum.c \\
pnp.c
pnp.c \\
power.c
power.c \\
buspdo.c
buspdo.c \\
32
wmi.c
wmi.c
mofcomp:
mofcomp: busenum.bmf
busenum.bmf
busenum.bmf:
busenum.bmf: busenum.mof
busenum.mof
mofcomp
mofcomp -B:busenum.bmf
-B:busenum.bmf busenum.mof
busenum.mof
wmimofck
wmimofck busenum.bmf
busenum.bmf
The Dirs File
Macro
The Makefile File
Meaning
DIRS=dir1 dir2 dir3 …
A list of subdirectories that the Build utility
will build every time it runs.
OPTIONAL_DIRS=dir4 dir5 …
A list of subdirectories that the Build utility
will build only if specified on the build.exe
command line.
Warning
Warning Do
Donot
notchange
changemakefile.def
makefile.defor
orany
anyof
ofthe
theother
otherfiles
filesininthe
the
DDK's
-specific make
DDK's\bin
\bindirectory.
directory.If
Ifyou
youhave
havedriver
driver-specific
makefile
filerequirements,
requirements,
put
them
in
makefile.inc
instead.
put them in makefile.inc instead.
// DIRS file: DIRS=dir1 dir2 dir3
//
OPTIONAL_DIRS=OptDir1 OptDir2 OptDir3
c:\> build OptDir1 OptDir2 OptDir3
means the same as:
c:\> set BUILD_OPTIONS=OptDir1 OptDir2 OptDir3
c:\> build
33
37
The Dirs File
Example (HelloWdm)
DIRS=
DIRS= \\
bus
bus \\
classinstaller
classinstaller \\
coinstaller
coinstaller \\
exe
exe \\
filter
filter \\
func
func \\
toastmon
toastmon \\
toastpkg
toastpkg
34
38
makefile.def
Example (HelloWdm)
The Makefile File
?
?
NMAKE uses makefile files to generate
dependency and command lists.
A standard makefile file in every sample driver's
source code directory directs NMAKE to the
master macro definition file, makefile.def.
–
?
The makefile you supply for your own source code should
do the same.
The makefile.def file is included with the DDK.
35
39
Example (HelloWdm)
The Makefile File
##
## DO
sources. if
DO NOT
NOT EDIT
EDIT THIS
THIS FILE!!!
FILE!!! Edit
Edit .\
.\sources.
if you
you want
want to
to add
add aa new
new source
source
## file
file to
to this
this component.
component. This
This file
file merely
merely indirects
indirects to
to the
the real
real make
make file
file
## that
that is
is shared
shared by
by all
all the
the driver
driver components
components of
of the
the Windows
Windows NT
NT DDK
DDK
##
!INCLUDE
makefile.def
!INCLUDE $(NTMAKEENV)\
$(NTMAKEENV)\makefile.def
36
40
Example (HelloWdm)
Prepare INF File
?
41
Wriate an INF file to install your driver
using Add Hardware wizard.
45
Example (HelloWdm)
Prepare the Driver Package
For Debugging: Using Network Neighbors to copy these files to
the target machine.
42
46
Driver Installation
Example (HelloWdm)
43
47
Driver Installation
Windows Driver Development
Getting Start
Installation
44
48
Driver Installation
49
Driver Installation
53
Select to the Inf file of the driver.
Driver Installation
50
Driver Installation
54
Driver Installation
51
Driver Installation
55
Driver Installation
52
Driver Installation
56
Select to the directory containing the .sys file.
Driver Installation
57
Device Manager
61
Driver Installation
58
Device Manager
62
Driver Files
Device Manager
59
63
Device Manager
60