Troubleshooting Device Installation with the Setupapi log File
|
Спампаваць 227 Kb.
|
Troubleshooting Device Installation with the SetupAPI Log File October 6, 2003 AbstractThis paper provides information about debugging device installation for Microsoft® Windows® XP and later versions of the operating system. Specifically, the paper provides guidelines for driver developers and testers to interpret the SetupAPI log file. ContentsIntroduction 3 1 How Is the SetupAPI Log File Organized? 3 2 Windows Installation Header Section 3 3 Device-Setup Class Installation Sections 4 4 Driver-Installation Sections 5 5 Device-Removal Sections 20 6 Common Device-Installation Problems 20 7 Appendix A: Setting the SetupAPI Logging Level 31 8 Appendix B: Message Formats 34 9 Appendix C: Section Markers 35 10 Appendix D: Definition of Example Placeholders 36 11 Call to Action and Resources 38 Disclaimer The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred. 2003 Microsoft Corporation. All rights reserved. Microsoft, Authenticode, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners. IntroductionThis paper provides information about debugging device installation for Microsoft® Windows® XP and later versions of the operating system. Windows XP and later versions log system operations more extensively than previous versions of Windows do. One of the most useful log files for debugging is the SetupAPI log file (setupapi.log). This plain-text file maintains the information that SetupAPI records about device installation, service-pack installation, and hotfix installation. Specifically, the file maintains a record of device and driver changes, as well as major system changes, beginning from the most recent Windows installation. This paper focuses on using the SetupAPI log file to troubleshoot device installation; the paper does not describe the log-file sections that are associated with service-pack and hotfix installations. Note SetupAPI consists of the Windows Setup functions and the Windows device-installation functions. For information about these functions, see “Setup API” in the Platform SDK documentation and “Using SetupAPI Functions” in the Windows Driver Development Kit (DDK) documentation. For general information about device installation, see “Device Installation Overview” in the DDK documentation. For information in the DDK documentation about SetupAPI logging, see “Using SetupAPI Logging.” 1How Is the SetupAPI Log File Organized?Each section of the SetupAPI log file begins with a section marker and contains the messages that pertain to a specific system operation. This paper describes the following types of sections, which are the ones that relate to device installation:
You can control the amount of information that is logged. How to do so is discussed later in this paper. 2Windows Installation Header SectionThe first section in a SetupAPI log file is the Windows installation header section, which specifies the platform and the system architecture. Here is an example of this type of section: [SetupAPI Log] OS Version = 5.1.2600 Service Pack 1 Platform ID = 2 (NT) Service Pack = 1.0 Suite = 0x0000 Product Type = 1 Architecture = x86 The first line in the example is the section marker, which also indicates the beginning of the log file. The remaining lines contain information about the operating system and computer architecture. Note If anyone deletes the SetupAPI log file after Windows has been installed, Windows creates a new SetupAPI log file and adds a Windows installation header section to it. 3Device-Setup Class Installation SectionsThe device-setup class installation sections, which immediately follow the Windows installation header section, record the installation of the system-supplied device-setup classes. SetupAPI adds these sections to the log file during the GUI-mode setup phase of Windows installation. The following example contains two sections that illustrate the default messages logged by SetupAPI: [2003/05/22 16:35:47 336.12] #-199 Executing "C:\WINDOWS\system32\setup.exe" with command line: setup –newsetup #I140 Installing Device Class: "1394" {6BDD1FC1-810F-11D0-BEC7-08002BE2092F}. #I141 Class install completed with no errors. [2003/05/22 16:35:48 336.15] #-199 Executing "C:\WINDOWS\system32\setup.exe" with command line: setup –newsetup #I140 Installing Device Class: "Battery" {72631e54-78a4-11d0-bcf7-00aa00b7b32a}. #I141 Class install completed with no errors The two lines in the example that contain the time stamps are the section markers. Each #199 message indicates that SetupAPI installed a device-setup class by executing the setup -newsetup command line, which in turn indicates that the device-setup class was installed during the GUI-mode setup phase of Windows installation. The #I140 messages specify the GUIDs of the device-setup classes. If an error occurs, SetupAPI does not log a #I141 message. Instead, it logs a #E142 error message that identifies the device-setup class GUID and the cause of the error. Here is an example of such an error message: #E142 Class: {FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFF}. Install failed. Error 1168: Element not found.
If anyone deletes the SetupAPI log file after Windows has been installed, Windows creates a new SetupAPI log file and adds a Windows installation header section to it. Therefore, the new log file will not contain any of the sections that SetupAPI added during the GUI-mode setup phase of Windows installation. Note Many of the examples in this paper contain placeholders, which appear in italics. For the definitions of these placeholders, see Appendix D: Definition of Example Placeholders. |