Skip to content

Commit e40a4c1

Browse files
jacob-ronstadtjacob-ronstadt
committed
update readme
1 parent 72208d3 commit e40a4c1

1 file changed

Lines changed: 31 additions & 48 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,88 +2,56 @@
22

33
This repository contains open-source components for supplemental use in developing device drivers for Windows, as well as driver specific [CodeQL](https://codeql.github.com/) query suites used for the [Windows Hardware Compatibility Program](https://learn.microsoft.com/en-us/windows-hardware/design/compatibility/). The quickstart below will get you set up to build your database and analyze your driver using CodeQL. For the full documentation, troubleshooting, and more details about the Static Tools Logo test within the WHCP Program, please visit [CodeQL and the Static Tools Logo Test](https://docs.microsoft.com/windows-hardware/drivers/devtest/static-tools-and-codeql).
44

5-
### For General Use
5+
### For General Use or Windows Hardware Compatibility Program Use
66

7-
| CodeQL CLI version | microsoft/windows-drivers qlpack version | microsoft/cpp-queries version | codeql/cpp-queries version |Associated Repo Branch|
8-
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|------------------------|
9-
| 2.20.1 | 1.5.0 | 0.0.2 | N/A | Main |
7+
| CodeQL CLI Version | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
8+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|
9+
| 2.20.1 | 1.6.0 | 0.0.4 | Main |
1010

11-
### For Windows Hardware Compatibility Program Use
11+
See appendix for more information
1212

13-
### Windows Hardware Compatibility Program Release Version Matrix
14-
| Release | CodeQL CLI version | microsoft/windows-drivers qlpack version| microsoft/cpp-queries version | codeql/cpp-queries version | Associated Repo Branch|
15-
|--------------------------|--------------------|-----------------------------------------|-------------------------------|-----------------------------|----------------------|
16-
| Windows Server 2022 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
17-
| Windows 11, version 22H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
18-
| Windows 11, version 23H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
19-
| Windows 11 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
20-
| Windows 11, version 24H2 | [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) | 1.1.0 | N/A |0.9.0 | WHCP_24H2 |
21-
| Windows Server 2025 | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.5.0 | 0.0.2 | N/A | WHCP_TODO |
22-
| Windows 11, version <todo> | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.5.0 | 0.0.2 | N/A | WHCP_TODO |
2313

2414

2515
### For Testing the Latest in Development
2616

2717

28-
| CodeQL CLI version | microsoft/windows-drivers qlpack version | microsoft/cpp-queries version | codeql/cpp-queries version |Associated Repo Branch|
29-
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|------------------------|
30-
| [Latest](https://github.com/github/codeql-cli-binaries/releases/latest) | [Latest](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | [Latest](https://github.com/orgs/microsoft/packages/container/package/cpp-queries) | N/A | Development |
18+
| CodeQL CLI Version | microsoft/windows-drivers CodeQL Pack Version | microsoft/cpp-queries CodeQL Pack Version | Associated Repo Branch|
19+
|--------------------------|------------------------------------------|-------------------------------|-----------------------------|
20+
| [Latest](https://github.com/github/codeql-cli-binaries/releases/latest) | [Latest Beta Version](https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/pkgs/container/windows-drivers) | [Latest](https://github.com/orgs/microsoft/packages/container/package/cpp-queries) | Development |
3121

3222
## Quickstart
3323

3424
1. Create a directory where you can place the CodeQL CLI and the queries you want to use:
3525
```
36-
D:\> mkdir codeql-home
26+
mkdir codeql-home
3727
```
3828
3929
1. Download the CodeQL CLI
4030
41-
**NOTE** Visual Studio 17.8 broke compatibility with the older versions of CodeQL used in the WHCP_21H2 and WHCP_22H2 branches. [CodeQL CLI version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) has been validated for use with WHCP 21H2 and WHCP 22H2 when using Visual Studio 17.8 or greater.
42-
43-
For the WHCP Program, use the CodeQL CLI version in accordance with the table above and Windows release you are certifying for
31+
For the WHCP Program, use the CodeQL CLI version specified above. For special cases and more information see appendix.
4432
1. Navigate to the [CodeQL CLI Release Page](https://github.com/github/codeql-cli-binaries/releases)
4533
1. Find the release version based on the tables above and select the asset associated with your OS and architecture (codeql-win64.zip, codeql-linux64.zip, etc.),
4634
1. Extract the downloaded zip to the directory you created in the previous step.
4735
1. (Optional) Add the CodeQL install location to your PATH
48-
49-
1. Verify CodeQL is installed correctly by checking the version:
50-
```
51-
D:\codeql-home\codeql>codeql --version
52-
CodeQL command-line toolchain release 2.15.4.
53-
Copyright (C) 2019-2023 GitHub, Inc.
54-
Unpacked in: D:\codeql-home\codeql
55-
Analysis results depend critically on separately distributed query and
56-
extractor modules. To list modules that are visible to the toolchain,
57-
use 'codeql resolve qlpacks' and 'codeql resolve languages'.
58-
```
36+
1. (Optional) Verify CodeQL is installed correctly by checking the version `codeql --version`
5937
6038
1. Install CodeQL Packages
6139
62-
63-
64-
Download the correct version of the CodeQL packs from the Windows Hardware Compatibility Program Release Version Matrix:
40+
Download the correct version of the CodeQL packs. For special cases and more information see appendix.
6541
```
6642
codeql pack download microsoft/windows-drivers@<version>
6743
```
6844
6945
```
70-
codeql pack download codeql/cpp-queries@<version>
46+
codeql pack download microsoft/cpp-queries@<version>
7147
```
7248
7349
CodeQL will install the packs to the default directory `C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\`. Do not change this directory or move the installed pack.
7450
75-
For examples, if using WHCP_24H2, run the following command to download query the microsoft/windows-drivers pack:
76-
77-
```
78-
codeql pack download microsoft/windows-drivers@1.1.0
79-
```
80-
81-
For special cases, see appendix below.
82-
8351
1. Build your CodeQL database:
8452
8553
```
86-
D:\codeql-home\codeql>codeql database create <path to new database> --language=cpp --source-root=<driver parent directory> --command=<build command or path to build file>
54+
codeql database create <path to new database> --language=cpp --source-root=<driver parent directory> --command=<build command or path to build file>
8755
```
8856
Single driver example: `codeql database create D:\DriverDatabase --language=cpp --source-root=D:\Drivers\SingleDriver --command="msbuild /t:rebuild D:\Drivers\SingleDriver\SingleDriver.sln"`
8957
@@ -112,7 +80,7 @@ This repository contains open-source components for supplemental use in developi
11280
11381
1. ***For WHCP Users Only***: Prepare to Create a Driver Verification Log (DVL):
11482
115-
Tocreate a DVL, your SARIF log file must be in the parent directory of your driver project. You can modify your output location in the `codeql database analyze` step or copy the file manyally
83+
To create a DVL, your SARIF log file must be in the parent directory of your driver project. You can modify your output location in the `codeql database analyze` step or copy the file manyally
11684
11785
Please refer to the continued instructions at [CodeQL and the Static Tools Logo Test, Driver Verification Log DVL Consumption of SARIF Output](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/static-tools-and-codeql#driver-verification-log-dvl-consumption-of-sarif-output).
11886
@@ -122,7 +90,7 @@ Windows drivers queries are in the `src/drivers` directory.
12290
12391
Non-driver Microsoft-specific queries provided by Microsoft are in the `src/microsoft` directory.
12492
125-
Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix and Recommended-Fix suites used by the WHCP Program.
93+
Query suites are located in the `windows-driver-suites` directory and contain the Must-Fix and Recommended suites used by the WHCP Program.
12694
12795
12896
@@ -163,7 +131,22 @@ Any use of third-party trademarks or logos are subject to those third-party's po
163131
164132
## Appendix
165133
134+
### Windows Hardware Compatibility Program Release Version Matrix
135+
For WHCP, these versions can be used in place of the latest versions specified above. These versions were the latest available at the time new WHCP requirements were released and can continue to be used for WHCP certifications. However, newer versions of CodeQL continue to be validated for use.
136+
| Release | CodeQL CLI version | microsoft/windows-drivers qlpack version| microsoft/cpp-queries version | codeql/cpp-queries version | Associated Repo Branch|
137+
|--------------------------|--------------------|-----------------------------------------|-------------------------------|-----------------------------|----------------------|
138+
| Windows Server 2022 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
139+
| Windows 11, version 22H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
140+
| Windows 11, version 23H2 | [2.6.3](https://github.com/github/codeql-cli-binaries/releases/tag/v2.6.3) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_22H2 |
141+
| Windows 11 | [2.4.6](https://github.com/github/codeql-cli-binaries/releases/tag/v2.4.6) or [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4)| 1.0.13 (If using codeql 2.15.4)| N/A |0.9.0 (If using codeql 2.15.4) | WHCP_21H2 |
142+
| Windows 11, version 24H2 | [2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) | 1.1.0 | N/A |0.9.0 | WHCP_24H2 |
143+
| Windows Server 2025 | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.6.0 | 0.0.4 | N/A | <todo> |
144+
| Windows 11, version <todo> | [2.20.1](https://github.com/github/codeql-cli-binaries/releases/tag/v2.20.1) | 1.6.0 | 0.0.4 | N/A | <todo> |
145+
146+
166147
### Special instructions for for WHCP_21H2 and WHCP_22H2 branches:
148+
Visual Studio 17.8 broke compatibility with the older versions of CodeQL used in the WHCP_21H2 and WHCP_22H2 branches. [CodeQL CLI version 2.15.4](https://github.com/github/codeql-cli-binaries/releases/tag/v2.15.4) has been validated for use with WHCP 21H2 and WHCP 22H2 when using Visual Studio 17.8 or greater.
149+
167150
168151
1. If using Visual Studio 2022 17.8 or greater with WHCP_21H2 or WHCP_22H2 and CodeQL CLI version 2.15.4:
169152

0 commit comments

Comments
 (0)