Kernel Memory Space Analyzer — Usage and Customization (Phase 3)
Last Updated: 12/25/99
2.5 Database Connection Parameters
3.2 Selecting a Mode of Operation
3.3 Specifying Crash Dump and
Signature Id Files
3.3.1 When There’s a Crash Dump File
3.3.2 When There’s no Crash Dump File
3.6.1 Crash Dump File but No Known
Issues Database
3.6.2 Crash Dump File and Known Issues
Database
3.6.3 Signature Id File and Known Issues
Database
4. SQL Scripts for Known Issues
Database
Kanalyze is really two things.
This document describes a particular kanalyze executable, namely the Wizard-based GUI program delivered as kanalyze.exe. Kanalyze.exe can be considered as the reference implementation of a kanalyze executable. It guides the user through the steps of dealing with the crash dump, signature id files, and symbols; provides support for connecting to and utilitizing a known issues database; and allows limited interaction with the debugging-oriented kanalyze features.
In addition, this document describes the parameters .ini file which is natively supported by the kanalyze engine. Changing this file provides customizability for the operation of the kanalyze executable described herein.
It also describes creation of a Known Issues Database using some supplied scripts.
Note: this document assumes familiarity with the concepts described in the kanalyze architecture document.
Table of Contents Ý
A kanalyze parameters file is a standard Windows .ini file. The file must be MBCS text and is interpreted in the current system ANSI codepage. A kanalyze executable typically reads the information out of a kanalyze parameters .ini file early in its operation and then does not refer to the actual on-disk file again. In this way the information in the parameters .ini file is shared among the kanalyze executable, the kanalyze engine, and the plug-ins. The kanalyze executable is free to display any parameters and allow user confirmation or override – in other words, the values for any or all of the parameters in the .ini file could just be default values.
Table of Contents Ý
So-called “global” parameters are in the [kanalyze] section of the parameters .ini file.
[kanalyze]
;
; The verbosity parameter is the verbosity level at which kanalyze
runs.
; Legal values are 0, 1, and 2. The default is 0.
;
verbosity = 2
;
; The loglevel parameter indicates
the verbosity level of the log,
; and optionally the file name of
the log file. Legal values for the
; level are 0, 1, 2, 3, and 4,
corresponding to fatal errors, errors,
; warnings, information, and details
(default is 2 – warnings). Items
; more verbose than the log level
are filtered out of the log at
; runtime. The file name is any
legal win32 file spec; the default log
; file name is kanalyze.log.
;
loglevel = 3,c:\foo\my_kanalyze_log.log
;
; The dumpfile parameter specifies
the win32 file spec of the
; crash dump file, which may or may
not be used, depending on the mode
; of operation of the kanalyze
executable.
;
dumpfile = d:\ka\memory.dmp
;
; The signature id file parameter
specifies the win32 file spec of the
; signature id file, which is either
loaded or created, depending on the
; mode of operation of the kanalyze
executable (in general, if a crash
; dump file is to be used, then this
parameter specifies the signature
; id file to be created; if a crash
dump file is not to be used, such as
; when a pre-existing signature id
file is used to perform database
; lookups, then this parameter
specifies an existing signature id file
; to be loaded). The default value
is sigidfil.sgd.
;
signature id file = d:\ka\mysigidfile.sgd
;
; The symoptions parameter specifies symbol loading options, which are
; which are the SYMOPT_xxx values in imagehlp.h, as a base-10 integer.
; The default is 35, which is 0x23 hex, corresponding to the bits
; SYMOPT_CASE_INSENSITIVE, SYMOPT_UNDNAME, and SYMOPT_OMAP_FIND_NEAREST.
;
symoptions [engine] = 39
;
; The disableexceptionhandler parameter indicates whether the engine
; encloses all callouts to plug-ins with try/except. Disabling this
; behavior can be useful for debugging. The default is 0 (i.e., enable
; the try/except enclosure).
;
disableexceptionhandler = 1
;
; The kanalyze engine caches portions of its data item backing
; store files and their index files in memory to help performance.
; The default behavior can be modified so that the caching is disabled
; (i.e., i/o to these files will all hit the actual files), and the
size
; of the cache can be controlled. The disablevmcache parameter is a
; Boolean indicating whether to disable the cache (default is 0).
; A value of 1 disables it. The vmcachesizekb overrides the default
size
; of 2048 (2MB) for each cache. The minimum value is 512.
;
disablevmcache = 1
vmcachesizekb = 1024
Table of Contents Ý
The [symbols] section is used for symbol loading. One line provides the default symbol path, and additional lines map individual module names to specific symbol files.
[symbols]
;
; The * line provides a win32 path that is the default symbol load path.
; Standard imagehlp symbol loading rules apply with this path.
; Additional lines are of the form <modulename> =
<filepath>, where
; <modulename> can the base name and file extension, or the base
name
; only. Internally, kanalyze looks for the base name and extension form
; first before trying the base name only form. <filepath> can
specify the
; actual file name or the
search path for that one module (if the given spec
; ends in .dbg or .pdb and exists as a file then it is assumed to
specify an
; actual symbol file. Otherwise it is assumed to be a symbol search
path).
;
* = d:\debugsym\nt4sp5\symbols
mydriver.sys = d:\debugsym\mydriver\symbols
myotherdriver =
d:\debugsym\myotherdriver\otherdriver.dbg
Table of Contents Ý
The module plug-in can attempt to match the read-only data areas of kernel memory space against the original images to ensure that no one overwrote data that is supposed to be read-only. The [binaries] section of the parameters .ini file is used for this purpose. The kanalyze engine will also make use of this section when the crash dump file is a minidump. Binaries in this case are useful, for example, to get adequate stack traces and perform other analysis-related tasks.
The * line in the [binaries] section provides the default path. Other lines map specific modules to individual search paths or actual binaries.
[binaries]
;
; The * line provides a win32 path that is the default binaries search
path.
; Standard imagehlp FindExecutableImageEx rules apply with this path.
; Additional lines are of the form <modulename> =
<filepath>, where
; <modulename> can the base name and file extension, or the base
name
; only. Internally, kanalyze looks for the base name and extension form
; first before trying the base name only form. <filepath> can
specify the
; actual file name or the
search path for that one module.
;
* = d:\binaries\nt4sp5
mydriver.sys = d:\mydriver\binary
Table of Contents Ý
The [plugins] section lists DLLs that should be loaded as plug-ins.
Each line specifies one DLL, either as an absolute Win32 file spec, or as a
relative path from top level path that is also supplied in this section. If a
DLL spec is not *, and starts with a \ or x:, then it is assumed to be an
absolute path name and is passed directly to LoadLobrary. Otherwise, the
kanalyze engine tries to load the DLL from 2 places:
[plugins]
;
; Each line specifies a plug-in DLL. The left hand sides of non-* lines
; in this section are not used. The right hand sides can be relative or
; absolute specs as described above. A right hand side of * indicates
; the root path for relative specs.
;
* = d:\kanalyze
objtbl.dll
kaio.dll
kobjects.dll
eobjects.dll
strace.dll
pool.dll
memory.dll
stopcode.dll
database.dll
Table of Contents Ý
The database-related plug-ins get their connection parameters from the
[query] section of the parameters .ini file. These parameters consist of a
connection string, a user ID string, and a password string. The parameters in
this section are generally shown by the kanalyze executable to the user for
confirmation before attempting a connection to the database, since the user ID
and password logically form a pair used for logging on to a SQL server.
The connection string is a legal OLE DB connection string. Its form is
inferred from the first few characters as follows.
[query]
;
; db_connect supplies a connection string spec as described above.
; dbuser_id supplies the user id for the connection. It overrides any
; Userid property specified in the connection string. If a userid
; property is specified, this parameter is therefore optional.
; db_passwd supplies the password for the connection. It overrides any
; Password property specified in the connection string. This parameter
; is optional and should be used with care since the password appears
; in clear-text.
;
db_connect = {DSN:}d:\kanalyze\kaknownissue_sql.dsn
db_userid = myuserid
db_passwd = mypassword
Table of Contents Ý
This section describes usage of the wizard-based kanalyze executable kanalyze.exe.
The invocation of kanalyze.exe is straightforward. All parameters are taken from a kanalyze parameters .ini file, which is specified on the command line.
kanalyze [-? | /? | -h | -H | /h | /H] [parametersfile]
-? (etc) — displays usage information in a message box, and then exits.
parametersfile — supplies the win32 path of the kanalyze parameters .ini file. If not specified, an attempt is made to load kanalyze.ini from the directory where the kanalyze.exe was loaded. If kanalyze.exe is renamed, the base name of the executable is used as the base name of the ini file to be loaded (i.e., if kanalyze.exe is renamed to foo.exe, an attempt is made to load foo.ini).
If the parameters .ini file is not specified and kanalyze.ini does not exist in the directory from which kanalyze.exe was loaded, kanalyze runs without a parameters .ini file and defaults are used. This is not a recommended or supported mode of operation.
Kanalyze.exe’s wizard pages each correspond to a step in the analysis process. The pages are described in the sections that follow.
Table of Contents Ý
The first page is a welcome page. Simply click Next to continue.
Table of Contents Ý
The next wizard page allows selection of a main mode of operation.
The top option is for use when the user has a crash dump file and access to a known issues database. In this case, kanalyze will make use of the known issues database and will also create a signature id file. Recall that database matching is not performed directly from the crash dump file; it is performed from the signature id file. The creation of the signature id file is thus an internal intermediary step that kanalyze takes in order that it be able to use the known issues database. The signature id file is not deleted at the end of the kanalyze invocation, so it can be used later to perform the database steps again.
The middle option is for use when the user has a crash dump file but does not have access to a known issues database. In this case, the signature id file is created for later use when there is access to a database.
The bottom option is for use when the user has a previously created signature id file, and access to a known issues database. Kanalyze will use the information in the signature id file to look for matching crashes in the database, update the database, etc.
Table of Contents Ý
The next wizard page allows specification of the crash dump file and the signature id file. The exact layout of the page and the available options depend on the mode of operation that was chosen in the previous step.
Table of Contents Ý
In the 2 modes of operation where the user has a crash dump file, kanalyze will be creating a new signature id file, and thus an existing crash dump file, plus the folder and file name to be used for the signature id file to be created, must be specified.
When the user clicks next, kanalyze attempts to load the dump file. Information from the dump header is displayed and the user is prompted to click Next to continue.
If the user clicks Back at this point, the dump file is unloaded and the previous page is again displayed, allowing the user to select a different dump file. Clicking Next goes to the symbols page.
Table of Contents Ý
In the mode of operation where kanalyze will be operating from a pre-existing signature id file, the location of a crash dump file is not required, but the location of an existing signature id file is.
When the user clicks Next in this case, operation proceeds to the confirmation page (assuming the specified signature id file exists and is valid).
Table of Contents Ý
Symbols are only required when there is a crash dump file. In the mode of operation where the user has specified that a pre-existing signature id file is to be used, no crash dump file is used and no symbols need be loaded. Thus the wizard page below will appear only when the user has selected a mode of operation that includes use of a crash dump file.
When the user clicks Next, kanalyze attempts to load symbols from the path specified. Text appears detailing the progress as symbols are loaded. When symbol loading is complete, the text at the top of the body of the wizard page changes to a prompt to click the Next button to continue.
In order for kanalyze to proceed, the symbols for at least the kernel must be loaded successfully. If kanalyze cannot load the symbols for the kernel, an error message appears and the user must specify a different path.
Table of Contents Ý
At this point, kanalyze presents a wizard page summarizing the user’s choices and the operations that will occur. A page similar to the one shown here appears.
Note that the information about the database connection is taken from the parameters .ini file; the user will have a chance to confirm or change these values before any connection to a database is actually attempted.
Following the confirmation in the previous step, kanalyze starts analysis. A new wizard page is displayed that presents status messages detailing kanalyze’s progress. The exact flow depends on the mode of operation chosen by the user.
Table of Contents Ý
In this mode of operation, kanalyze immediately proceeds to full analysis, which fully populates the signature id file. Status messages appear to indicate analysis progress. When analysis is complete, the user is prompted to click Next to continue.
Following this, the results page is displayed.
Table of Contents Ý
In this mode of operation, the first action in analysis is to perform an initial database query to determine whether the same crash has been encountered before and is in the database. The user is quickly prompted for database connection parameters.
The Database parameter is a legal SQL connection string. The username and password must be valid on the data source for successful connection. When the user clicks OK, kanalyze attempts a connection. If the connection is unsuccessful, an error message is displayed and the user can specify different database parameters to try again.
If connection is successful, the user is so informed and must click Next to continue. The next page shows the results of the initial database query, which indicates whether a record of the same crash (i.e., stop code and 4 bugcheck parameters match the current crash dump file) exists in the database.
In this case, the crash was not found in the database. The only option is to continue on to full analysis, which will determine whether any similar crashes exist in the database. Full analysis proceeds as described in the previous section.
In the case where the crash was found in the database, the options expand to include the ability to perform a database update. The option to perform a full analysis also exists, but is not generally necessary (performing a full analysis will generate a fully populated signature id file).
Clicking View will display a record browser. Clicking Next will take the user to the database update page unless “Continue to full analysis” is selected. In that case a full analysis occurs.
Table of Contents Ý
In this case, a known issues database will be searched using a previously created signature id file. There is no crash dump file in use. Recall that in the crash dump file case, kanalyze as an interim step builds a signature id file, and it is that signature id file that is used for database matching.
Thus this mode of operation is the same as the mode where there is a crash dump file and a known issues database is to be searched.
Table of Contents Ý
The master results page is displayed if full analysis occurs, after the analysis has completed. (If full analysis does not occur, such as when a database prequery finds matches and the user elects to skip full analysis, this page does not appear.)
Depending on the actual results, some or all of the View buttons may be disabled and the text may not look exactly as pictured above.
“Anamalous conditions” refers to kanalyze anomalies. These will be represented as data items in the AnomalyDescriptor branch of the namespace hierarchy. Clicking the View button for anomalies will display the namespace browser for this branch.
Note that most if not all crash dumps will contain inaccessible (i.e., paged out) memory areas and so these are not necessarily problematic.
“Analysis conclusions” refers to any automated determinations or recommendations kanalyze is able to make regarding the crash. Clicking the View button will bring up the namespace browser for the Analysis brance of the namespace; the user should check the Summary sub-branch.
“Information from the database” refers to matches that were found in the known issues database, if one was searched, in the main query (as opposed to the prequery). Clicking the View button will bring up the namespace browser for Analysis\DbMatching.
Additional information is available by clicking the “Analysis Record” and “Solution Record” tabs. These display information from the database relating to matched crash classes.
Te Advanced button will bring up the namespace browser for the entire hierarchy, showing base data items as well as the abstract ones relating to database matching and analysis results. Note that the browser can take several minutes to appear when invoked from the Advanced button.
The population of the hierarchy will vary depending on the kanalyze mode of operation, plug-ins that were participating in the analysis, etc.
Finally, the “Continue to update the known issues database” checkbox allows the user to skip database updates. If this box is unchecked, the Next button changes to “Finish” and clicking it exits kanalyze. Otherwise, clicking Next proceeds to the database update page.
Table of Contents Ý
The database update page allows the known issues database to be updated. The exact options depend on whether existing matching crashes were found in the database.
For example, in the case where matching crashes were found, the options are to create a new crash instance in one of the matching crash’s crash class, or to create a new crash class (the crash being analyzed will be the first instance of the new class).
Clicking the Details button will show information about the crash class currently shown in the combo box. This can be useful to help decide which class should be updated, in the case where more than one existing crash class matched.
After the user clicks Next, the database is updated. Status is shown and upon successful completion the Next button is changed to Finish.
Table of Contents Ý
Kanalyze includes some SQL scripts that can be used to create and maintain a known issues database on a SQL server. They are descripbed in the sections that follow.
Table of Contents Ý
The “KaKnownIssue” database is created using the KaCreateDb.sql script as follows:
Alternately, the database can be populated with tables (constraints enabled) and a set of test data by replacing step 3 with the following step:
3alt. Run the following scripts in the order listed:
KaPopDBObjectsNoConstraints.sql, KaPopDBTableswithTestData.sql,
KaEnableDBConstraints.sql.
Table of Contents Ý
Run these SQL scripts in the order listed to drop the constraints and the database tables:
Once the constraints and tables are dropped, the database tables can be created again and populated with data.
Table of Contents Ý
In some cases, duplicate records can appear in the database due to phase 3 implementation limitations. It is recommended that periodically, a cleanup script be run. The cleanup script will delete duplicated records. The cleanup script is kadbcleanup.sql (ensure that the database name listed therein matches the name of the database you created, for example, “KaKnownIssue.”).
Table of Contents Ý