Skip to content

Commit

Permalink
Updates to README.md to add more detail to setup steps (#3)
Browse files Browse the repository at this point in the history
  • Loading branch information
sfudally authored Sep 28, 2023
1 parent ee29342 commit b2a5df9
Show file tree
Hide file tree
Showing 3 changed files with 60 additions and 28 deletions.
85 changes: 57 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,50 @@

This is a Rust port of the driver samples from the original [Windows Driver Samples on Github.](https://github.com/microsoft/Windows-driver-samples)

The repository provides examples and best practices for Windows driver development in Rust using crates from [windows-drivers-rs.](https://github.com/microsoft/windows-drivers-rs) <span style="background-color: #FFFF00"></span>
The repository provides examples and best practices for Windows driver development in Rust using crates from [windows-drivers-rs.](https://github.com/microsoft/windows-drivers-rs)

## Getting Started

### Pre-requisites

#### Required
* Set up [EWDK Build Environment.](https://learn.microsoft.com/en-us/windows-hardware/drivers/develop/using-the-enterprise-wdk)
* Install [Clang.](https://clang.llvm.org/get_started.html)
* Install [Rust.](https://www.rust-lang.org/tools/install)

* Set up [EWDK Build Environment](https://learn.microsoft.com/en-us/windows-hardware/drivers/develop/using-the-enterprise-wdk)
* Easy install option:
* Install the latest version from link
* <https://learn.microsoft.com/en-us/legal/windows/hardware/enterprise-wdk-license-2022>
* Expand the ISO image to c:\ewdk
* Start Environment by running in command prompt:
* ```c:\ewdk\LaunchBuildEnv.cmd```
* Install [Clang](https://clang.llvm.org/get_started.html)
* Easy install option:
* `winget install LLVM.LLVM`

* Install [Rust](https://www.rust-lang.org/tools/install)
* Easy install option for x64 systems:

```pwsh
Invoke-RestMethod -Uri "https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe" -OutFile "$env:USERPROFILE\Downloads\rustup-init.exe"
& "$env:USERPROFILE\Downloads\rustup-init.exe" -y
```

#### Rust Setup

Run the following commands after setting up Rust.
* `rustup toolchain add nightly-msvc`
* `cargo install cargo-make --no-default-features --features tls-native`

`cargo install cargo-make --no-default-features --features tls-native`

__Note on arm64: ARM64 support for ring is [not released yet](https://github.com/briansmith/ring/issues/1167), so TLS features must be disabled until arm64 is officially supported by ring (probably in 0.17.0 release)__

##### Optional

These are not-required, but may make it easier to work in a rust environment:

* `cargo install cargo-expand`
* `cargo install cargo-edit`
* `cargo install cargo-workspaces`
`cargo install cargo-expand cargo-edit cargo-workspaces`

## Documentation

Use `cargo doc --document-private-items --open` to compile and open documentation
`cargo doc --document-private-items --open`

## Build and Test

Expand All @@ -40,25 +55,38 @@ From an EWDK development command prompt, run:

`cargo make`

If build is successful, this will stamp the INF and create a CAT file placed with driver binary and INF in `Package` folder.
If build is successful, this will stamp the INF and create a CAT file placed with driver binary and INF in `Package` folder.

### Install

#### One Time PC Setup

1. If Bitlocker is enabled, suspend Bitlocker
Example: `manage-bde -protectors -disable C:`
1. Turn off Secure Boot via your UEFI/BIOS Settings
Example: `shutdown -r -o -t 0` then pick Advanced -> UEFI Settings
1. If Bitlocker is enabled, suspend Bitlocker again
Example: `manage-bde -protectors -disable C:`
1. Turn on test signing
`bcdedit /set testsigning on`
1. Reboot
`shutdown -r -t 0`

1. Copy the following to the DUT (Device Under Test: the computer you want to test the driver on):
1. `.\target\..configuration..\package`
2. `Path\To\Driver\DriverCertificate.cer`
3. The version of `devgen.exe` from the WDK Developer Tools that matches the archtecture of your DUT
* Ex. `C:\Program Files\Windows Kits\10\Tools\10.0.22621.0\x64\devgen.exe`
2. Install the Certificate on the DUT:
1. `Path\To\Driver\DriverCertificate.cer`
1. The version of `devgen.exe` from the WDK Developer Tools that matches the archtecture of your DUT
* Ex. `C:\ewdk\Program Files\Windows Kits\10\Tools\10.0.22621.0\x64\devgen.exe`
1. Install the Certificate on the DUT:
1. Double click the certificate
2. Click Install Certificate
3. Select a Store Location __(Either Store Location is Fine)__ -> Next
4. Place all certificates in the following Store -> Browse -> Trusted Root Certification Authorities -> Ok -> Next
5. Finish
3. Install the driver:
* In the package directory, run: `pnputil.exe /add-driver echo_2.inf /install`
4. Create a software device:
* In the directory that `devgen.exe` was copied to, run: `devgen.exe /add /hardwareid "root\ECHO_2"`
1. Click Install Certificate
1. Store Location: Local Machine -> Next
1. Place all certificates in the following Store -> Browse -> Trusted Root Certification Authorities -> Ok -> Next
1. Finish
1. Install the driver from Admin Command Prompt:
1. In the package directory, run: `pnputil.exe /add-driver echo_2.inf /install`
1. Create a software device from Admin Command Prompt:
1. In the directory that `devgen.exe` was copied to, run: `devgen.exe /add /hardwareid "root\ECHO_2"`

### Test

Expand All @@ -73,9 +101,10 @@ If build is successful, this will stamp the INF and create a CAT file placed wit
### Usage

The echo driver can be tested by using the [echo executable](https://github.com/microsoft/Windows-driver-samples/tree/main/general/echo/kmdf/exe)
- Echoapp.exe --- Send single write and read request synchronously

- Echoapp.exe -Async --- Send 100 reads and writes asynchronously
* Echoapp.exe --- Send single write and read request synchronously

* Echoapp.exe -Async --- Send 100 reads and writes asynchronously

Exit the app anytime by pressing Ctrl-C

Expand Down Expand Up @@ -103,8 +132,8 @@ For information about important changes that need to be made to the WDK sample d

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.
1 change: 1 addition & 0 deletions general/echo/kmdf/driver/DriverSync/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
name = "echo-2"
version = "0.1.0"
license = "MIT OR Apache-2.0"
rust-version = "1.72.1"
edition.workspace = true
publish.workspace = true

Expand Down
2 changes: 2 additions & 0 deletions rust-toolchain.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
[toolchain]
channel = "stable"

0 comments on commit b2a5df9

Please sign in to comment.