Skip to content

Commit 79ee5eb

Browse files
ikrimaikrima
committed
win: add debugging Windows Device/Drivers Install guide
1 parent ecd452f commit 79ee5eb

File tree

1 file changed

+184
-55
lines changed
  • docs/dev-notes/win-internals/win-debug-recipes/components

1 file changed

+184
-55
lines changed

‎docs/dev-notes/win-internals/win-debug-recipes/components/win-drivers.md‎

Lines changed: 184 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,135 @@
1-
# Drivers
1+
# Troubleshooting Windows Drivers
22

3-
## SetupAPI Logs
3+
## Check For Device Problems
4+
5+
- use [DeviceManager](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/using-device-manager) to see if the device has a [problem code](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/devpkey-device-problemcode)
6+
7+
- check all devices for problem
8+
9+
```batch
10+
pnputil /enum-devices /problem
11+
```
12+
13+
- check specific [device instance path](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/device-instance-ids)
14+
15+
```batch
16+
pnputil /enum-devices /instanceid <device instance path>
17+
```
18+
19+
## Check For Device Installation Problems
20+
21+
>
22+
> \[!TLDR\] Analyzing the Setupapi.dev.log File
23+
> Check the `%windir%\\inf\setupapi.dev.log` driver installation log file; lines beginning with "!" are _**warnings**_ and "!!!" are _**error failures**_
24+
25+
### SetupAPI Text Logs: Device Driver Installation Logs
26+
27+
_**Plug n Play Manager**_ and _**SetupAPI**_ log information about installation events:
428

529
|Log|Purpose<sup>
630
[1](https://github.com/MicrosoftDocs/windows-driver-docs/blob/staging/windows-driver-docs-pr/install/setupapi-text-logs.md "SetupAPI Logs Reference")</sup>|
731
|---|--------|
832
|`C:\Windows\INF\setupapi.dev.log`|_Device Installation Log_ on device/driver installs|
933
|`C:\Windows\INF\setupapi.app.log`|_App Installation Log_ on app installs associated w/device driver installs|
1034

11-
## Approach 1: AutoRuns
35+
#### SetupAPI Logging Registry Settings
36+
37+
[SetupAPI](setupapi.md) logging supports:
38+
39+
- _**global event level:**_ controls log verbosity level; see [Setting the Event Level for a Text Log](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/setting-the-event-level-for-a-text-log)
40+
- _**global event category:**_ determines the type of operations that can make log entries; see [Enabling Event Categories for a Text Log](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/enabling-event-categories-for-a-text-log)
41+
42+
#### Interpreting SetupAPI Log File
43+
44+
SetupAPI text logs internal format:
45+
46+
- _**log entry:**_ is one line in a text log
47+
48+
- _**text log header:**_ info about the os and computer architecture. see [Format of a Text Log Header](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/format-of-a-text-log-header).
49+
50+
- _**text log sections:**_ records the events during a single device installation; sections used to conceptually organize log entries in meaningful way
51+
52+
- _**non-section log entries:**_ associated with operations not tied to specific section; appear in order they're written. see [Format of Log Entries That Are Not Part of a Text Log Section](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/format-of-log-entries-that-are-not-part-of-a-text-log-section)
53+
their log entry format: _**entry_prefix** **time_stamp** **event_category** **formatted_message**_
54+
55+
|`Entry Prefix`|Message type|
56+
|:-------------|:-----------|
57+
|"!!! "|error message|
58+
|"! "|warning message|
59+
|" "|info message|
60+
|" . "|info message|
61+
62+
|`Event Category`|SetupAPI operation|
63+
|----------------|------------------|
64+
|"...: "|Vendor-supplied operation|
65+
|"bak: "|Backup data|
66+
|"cci: "|Class installer or co-installer operation|
67+
|"cpy: "|Copy files|
68+
|"dvi: "|Device installation|
69+
|"flq: "|Manage file queues|
70+
|"inf: "|Manage INF files|
71+
|"ndv: "|New device wizard|
72+
|"prp: "|Manage device and driver properties|
73+
|"reg: "|Manage registry settings|
74+
|"set: "|General setup|
75+
|"sig: "|Verify digital signatures|
76+
|"sto: "|Manage the driver store|
77+
|"ui : "|Manage user interface dialog boxes|
78+
|"ump: "|User-mode PnP manager|
79+
80+
#### Example Log File
81+
82+
```cpp
83+
>>> [Device Install - PCI\VEN_104C&DEV_8019&SUBSYS_8010104C&REV_00\3&61aaa01&0&38]
84+
>>> 2005/02/13 22:06:28.109: Section start
85+
...
86+
Additional section body log entries
87+
...
88+
dvi: {Build Driver List}
89+
dvi: Enumerating all INFs...
90+
dvi: Found driver match:
91+
dvi: HardwareID - PCI\VEN_104C&DEV_8019
92+
dvi: InfName - C:\WINDOWS\inf\1394.inf
93+
dvi: DevDesc - Texas Instruments OHCI Compliant IEEE 1394 Host Controller
94+
dvi: DrvDesc - Texas Instruments OHCI Compliant IEEE 1394 Host Controller
95+
dvi: Provider - Microsoft
96+
dvi: Mfg - Texas Instruments
97+
dvi: InstallSec - TIOHCI_Install
98+
dvi: ActualSec - TIOHCI_Install.NT
99+
dvi: Rank - 0x00002001
100+
dvi: DrvDate - 10/01/2002
101+
dvi: Version - 6.0.5033.0
102+
!!! inf: InfCache: Error flagging 1394.inf for match string pci\ven_104c&dev_8019
103+
dvi: {Build Driver List - exit(0x00000000)}
104+
...
105+
Additional section body log entries
106+
...
107+
<<< [2005/02/13 22:06:29.000: Section end]
108+
<<< [Exit Status(0x00000000)]
109+
```
110+
111+
```cpp
112+
. ump: Start service install for: PCI\VEN_104C&DEV_8019&SUBSYS_8010104C&REV_00\3&61aaa01&0&38
113+
. ump: Creating Install Process: rundll32.exe
114+
115+
>>> [Device Install - PCI\VEN_104C&DEV_8019&SUBSYS_8010104C&REV_00\3&61aaa01&0&38]
116+
>>> 2005/02/13 22:06:28.109: Section start
117+
```
118+
119+
### Common Installation Errors Errors
120+
121+
|Error code|Description|
122+
|----------|-----------|
123+
|0x000005B4 (ERROR_TIMEOUT)|The device installation took too long and was stopped. See [SetupApi logs](setupapi-text-logs.md) for more information about the device installation and where the time was spent.<br><br>Some common causes of timeouts are:<br><br>A co-installer executing for too long. This could be because the co-installer is performing some unsupported operation that has hung or is too long running. For example, a co-installer is executed in a non-interactive session, so it can't do something that needs to wait on user input. Co-installers are deprecated and should be avoided. For more information, see [universal INFs](using-a-universal-inf-file.md).<br><br>Starting or restarting a device at the end of device installation has hung.|
124+
|0xe0000219 (ERROR_NO_ASSOCIATED_SERVICE)|The driver package being installed on the device didn't specify an associated service for the device. For more information, see the SPSVCINST_ASSOCSERVICE flag in the [INF AddService Directive](inf-addservice-directive.md) documentation.|
125+
|0xe0000248 (ERROR_DEVICE_INSTALL_BLOCKED)|The installation of the device was blocked due to group policy settings. For more information, see [controlling device installation using Group Policy](/previous-versions/dotnet/articles/bb530324(v=msdn.10)) and [Mobile Device Management policies for device installation](/windows/client-management/mdm/policy-csp-deviceinstallation).|
126+
|0x000001e0 (ERROR_PNP_QUERY_REMOVE_DEVICE_TIMEOUT)|At the end of device installation, one or more devices will be restarted to pick up new files or settings changed during the device installation. As part of this restart operation, a query remove operation is performed on the device or devices being restarted. This error indicates that something hung or took too long during the query remove operation for the device being installed. For more information, see [SetupApi logs](setupapi-text-logs.md).|
127+
|0x000001e1 (ERROR_PNP_QUERY_REMOVE_RELATED_DEVICE_TIMEOUT)|At the end of device installation, one or more devices will be restarted to pick up new files or settings changed during the device installation. As part of this restart operation, a query remove operation is performed on the device or devices being restarted. This error indicates that something hung or took too long during the query remove operation for one of the device or devices being restarted. For more information, see [SetupApi logs](setupapi-text-logs.md).|
128+
|0x000001e2 (ERROR_PNP_QUERY_REMOVE_UNRELATED_DEVICE_TIMEOUT)|At the end of device installation, one or more devices will be restarted to pick up new files or settings changed during the device installation. As part of this restart operation, a query remove operation is performed on the device or devices being restarted. This error indicates that that query remove operation wasn't able to be performed in a timely manner due to a query remove operation being performed on another device on the system. For more information, see [SetupApi logs](setupapi-text-logs.md).|
129+
130+
## Misbehaving Or Bad Drivers
131+
132+
### Approach 1: AutoRuns
12133

13134
- TLDR: use **_SysInternals: AutoRuns_** to find bad behaving/suspect drivers [(Reference)](https://www.overclock.net/threads/official-amd-ryzen-ddr4-24-7-memory-stability-thread.1628751/page-1041)
14135
- Configuration
@@ -63,7 +184,7 @@
63184
- [SystemInformer](https://systeminformer.sourceforge.io)
64185
- TaskManager/msconfig
65186

66-
## Approach 2: SCManager
187+
### Approach 2: SCManager
67188

68189
`sc.exe`: **Service Control Manager CLI** to manipulate services; drivers run as special kernel service
69190

@@ -101,63 +222,68 @@
101222
```
102223
103224
- Global Commands: operate on SCManager; does not take service name
104-
\| Command | Description |
105-
\| -------------- | -------------------------------------------------------------------------------------------------- |
106-
\| `sc [command]` | get help for command |
107-
\| `boot` | `ok|bad` Indicates whether the last boot should be saved as the last-known-good boot configuration |
108-
\| `Lock` | Locks the Service Database |
109-
\| `QueryLock` | Queries the LockStatus for the SCManager Database |
225+
226+
|Command|Description|
227+
|-------|-----------|
228+
|`sc [command]`|get help for command|
229+
|`boot`|\`ok|
230+
|`Lock`|Locks the Service Database|
231+
|`QueryLock`|Queries the LockStatus for the SCManager Database|
110232
111233
- Service Commands: operates on services; requires service name
112-
\| Command | Description |
113-
\| ----------------- | -------------------------------------------------------------------------------------------------- |
114-
\| `query` | Queries the status for a service, or enumerates the status for types of services |
115-
\| `queryex` | Queries the extended status for a service, or enumerates the status for types of services |
116-
\| `start` | Starts a service |
117-
\| `pause` | Sends a PAUSE control request to a service |
118-
\| `interrogate` | Sends an INTERROGATE control request to a service |
119-
\| `continue` | Sends a CONTINUE control request to a service |
120-
\| `stop` | Sends a STOP request to a service |
121-
\| `config` | Changes the configuration of a service (persistent) |
122-
\| `description` | Changes the description of a service |
123-
\| `failure` | Changes the actions taken by a service upon failure |
124-
\| `failureflag` | Changes the failure actions flag of a service |
125-
\| `sidtype` | Changes the service SID type of a service |
126-
\| `privs` | Changes the required privileges of a service |
127-
\| `managedaccount` | Changes the service to mark the service account password as managed by LSA |
128-
\| `qc` | Queries the configuration information for a service |
129-
\| `qdescription` | Queries the description for a service |
130-
\| `qfailure` | Queries the actions taken by a service upon failure |
131-
\| `qfailureflag` | Queries the failure actions flag of a service |
132-
\| `qsidtype` | Queries the service SID type of a service |
133-
\| `qprivs` | Queries the required privileges of a service |
134-
\| `qtriggerinfo` | Queries the trigger parameters of a service |
135-
\| `qpreferrednode` | Queries the preferred NUMA node of a service |
136-
\| `qmanagedaccount` | Queries whether a services uses an account with a password managed by LSA |
137-
\| `qprotection` | Queries the process protection level of a service |
138-
\| `quserservice` | Queries for a local instance of a user service template |
139-
\| `delete` | Deletes a service (from the registry) |
140-
\| `create` | Creates a service. (adds it to the registry) |
141-
\| `control` | Sends a control to a service |
142-
\| `sdshow` | Displays a service's security descriptor |
143-
\| `sdset` | Sets a service's security descriptor |
144-
\| `showsid` | Displays the service SID string corresponding to an arbitrary name |
145-
\| `triggerinfo` | Configures the trigger parameters of a service |
146-
\| `preferrednode` | Sets the preferred NUMA node of a service |
147-
\| `GetDisplayName` | Gets the DisplayName for a service |
148-
\| `GetKeyName` | Gets the ServiceKeyName for a service |
149-
\| `EnumDepend` | Enumerates Service Dependencies |
234+
235+
|Command|Description|
236+
|-------|-----------|
237+
|`query`|Queries the status for a service, or enumerates the status for types of services|
238+
|`queryex`|Queries the extended status for a service, or enumerates the status for types of services|
239+
|`start`|Starts a service|
240+
|`pause`|Sends a PAUSE control request to a service|
241+
|`interrogate`|Sends an INTERROGATE control request to a service|
242+
|`continue`|Sends a CONTINUE control request to a service|
243+
|`stop`|Sends a STOP request to a service|
244+
|`config`|Changes the configuration of a service (persistent)|
245+
|`description`|Changes the description of a service|
246+
|`failure`|Changes the actions taken by a service upon failure|
247+
|`failureflag`|Changes the failure actions flag of a service|
248+
|`sidtype`|Changes the service SID type of a service|
249+
|`privs`|Changes the required privileges of a service|
250+
|`managedaccount`|Changes the service to mark the service account password as managed by LSA|
251+
|`qc`|Queries the configuration information for a service|
252+
|`qdescription`|Queries the description for a service|
253+
|`qfailure`|Queries the actions taken by a service upon failure|
254+
|`qfailureflag`|Queries the failure actions flag of a service|
255+
|`qsidtype`|Queries the service SID type of a service|
256+
|`qprivs`|Queries the required privileges of a service|
257+
|`qtriggerinfo`|Queries the trigger parameters of a service|
258+
|`qpreferrednode`|Queries the preferred NUMA node of a service|
259+
|`qmanagedaccount`|Queries whether a services uses an account with a password managed by LSA|
260+
|`qprotection`|Queries the process protection level of a service|
261+
|`quserservice`|Queries for a local instance of a user service template|
262+
|`delete`|Deletes a service (from the registry)|
263+
|`create`|Creates a service. (adds it to the registry)|
264+
|`control`|Sends a control to a service|
265+
|`sdshow`|Displays a service's security descriptor|
266+
|`sdset`|Sets a service's security descriptor|
267+
|`showsid`|Displays the service SID string corresponding to an arbitrary name|
268+
|`triggerinfo`|Configures the trigger parameters of a service|
269+
|`preferrednode`|Sets the preferred NUMA node of a service|
270+
|`GetDisplayName`|Gets the DisplayName for a service|
271+
|`GetKeyName`|Gets the ServiceKeyName for a service|
272+
|`EnumDepend`|Enumerates Service Dependencies|
150273
151274
- `query/queryex` options
152275
153276
- query service status: `sc query [servicename]`
277+
154278
- find matching services: `sc query [option]`
155-
\| Option | Value Type | Description |
156-
\| ---------- | ------------------------- | --------------------------------------------------------------- |
157-
\| `state=` | `active`,`inactive`,`all` | service state to enumerate; default: `active` |
158-
\| `bufsize=` | `int` | size in bytes of enumeration buffer; default: `4096` |
159-
\| `ri=` | `int` | resume index number to begin enumeration; default: `0` |
160-
\| `group=` | `string` | service group to enumerate; default: `all groups` |
279+
280+
|Option|Value Type|Description|
281+
|------|----------|-----------|
282+
|`state=`|`active`,`inactive`,`all`|service state to enumerate; default: `active`|
283+
|`bufsize=`|`int`|size in bytes of enumeration buffer; default: `4096`|
284+
|`ri=`|`int`|resume index number to begin enumeration; default: `0`|
285+
|`group=`|`string`|service group to enumerate; default: `all groups`|
286+
161287
- syntax examples
162288
163289
```batch
@@ -174,11 +300,13 @@
174300
sc query type= driver group= NDIS - Enumerates all NDIS drivers
175301
```
176302
177-
## Approach 3: pnputil
303+
### Approach 3: pnputil
178304
179305
- find bad offender's by looking at [zombie processes](https://scorpiosoftware.net/2022/05/14/zombie-processes/) using Pavel's Object Explorer
306+
180307
- ex: Razer's shitty GameManagerService.exe that's forced on users for no reason
181308
- list/inspect
309+
182310
- AutoRuns
183311
- DriverView
184312
- DevManView
@@ -192,6 +320,7 @@
192320
```
193321
194322
- delete
323+
195324
- BCUninstaller
196325
- BleachBit
197326
- command line

0 commit comments

Comments
 (0)