diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 132 | ||||
| -rw-r--r-- | utils/README.md | 36 | ||||
| -rw-r--r-- | utils/libnt_path_converter/README.md | 35 | ||||
| -rw-r--r-- | utils/libservice/README.md | 44 | ||||
| -rw-r--r-- | utils/libtest/README.md | 33 |
5 files changed, 157 insertions, 123 deletions
@@ -1,66 +1,84 @@ # Windows 7 drivers -This is a collection of basic Windows 7 drivers. -These are actually not drivers as such (in the sense that they don't actually -manage any hardware), but rather kernel modules. +A collection of basic Windows 7 drivers. + +These are actually not drivers as such in the sense that they don't actually +manage any hardware. +The author prefers calling them *kernel modules*. ## Development ### Prerequisites -The drivers are compiled using the Windows Driver Kit Version 7.1.0. - -I've developed a set of batch files to facilitate building the drivers and -cleaning after the build. -The binaries are copied into the "bin" directory under the root directory. - -To set up the development environment, start a new `cmd` session, and run +The drivers are compiled using [Windows Driver Kit 7.1.0]. +Install the "Build Environments" distributed with the kit, launch the Command +Prompt, and execute (to target x86): C:\WinDDK\7600.16385.1\bin\setenv.bat C:\WinDDK\7600.16385.1 fre WIN7 no_oacr -Of course, you may want to provide other `setenv.bat` parameters according to -your needs. -For example, to compile for x86-64, call `setenv.bat` like this: +or (to target x86-64): C:\WinDDK\7600.16385.1\bin\setenv.bat C:\WinDDK\7600.16385.1 fre x64 WIN7 no_oacr -Then navigate to the root directory and call `setenv.bat`: +Then `cd` to the project's root directory and execute `setenv.bat`: setenv.bat ### Code signing -Driver binaries are signed using the self-signed certificate issued by -"windows7_drivers" from "Trusted Root Certification Authorities" store. -You can generate this certificate using `add_cert.bat` (make sure to set up the -development environment first). +The binaries are signed using the self-signed certificate issued by +"windows7_drivers". +The certificate must be stored in the "Trusted Root Certification Authorities" +store. +To generate such a certificate, execute `add_cert.bat`: + + add_cert.bat + To verify it's there, you can use the `certmgr.msc` utility. -Driver binaries are automatically signed during builds, but you can also sign -one manually by passing the path to a .sys file to `sign.bat`. +The binaries are signed automatically after they are built, but you can also +sign manually by passing the path to a .sys file to `sign.bat`: + + sign.bat C:\workspace\personal\windows7-drivers\bin\x64\Release\test.sys + +### Building + +To build every driver under the "src/" directory, execute `build_drivers.bat`: + + build_drivers.bat + +To build a particular driver, pass the path to the driver's source directory to +`build_driver.bat`: -### Build & clean + build_driver.bat C:\workspace\personal\windows7-drivers\src\test -To build every driver under the "src" directory, call `build_drivers.bat`. -To build a particular driver, pass the path to the driver source directory to -`build_driver.bat`. -Driver binaries are copied to the "bin" directory. +Driver binaries are copied to the "bin/" directory under the project's root. -Cleaning after a driver build includes deleting log and object files in the -driver source directory and deleting the binaries from the "bin" directory. -To clean after every driver in the "src" directory, call `clean_drivers.bat`. -To clean after a particular driver, pass the path to the driver source -directory to `clean_driver.bat`. +### Cleaning up + +Cleaning up after building a driver includes deleting the log and object files +produced during the build as well as purging the binaries from the "bin/" +directory. + +To clean up after building every driver in the "src/" directory, execute +`clean_drivers.bat`: + + clean_drivers.bat + +To clean up after building a particular driver, pass the path to the driver's +source directory to `clean_driver.bat`: + + clean_driver.bat C:\workspace\personal\windows7-drivers\src\test ## Installation -To install a driver as a service, you can use the `sc` utility. -For example, to install a driver "C:\test.sys" as a "test" service, run +To install a driver as a Windows service, you can use the `sc` utility (`test` +is the name of the service): - sc create test type= kernel binPath= C:\test.sys + sc create test type= kernel binPath= C:\workspace\personal\windows7-drivers\bin\x64\Release\test.sys -You can then load/unload the driver by using the `net` utility to start/stop -the corresponding service. +You can then load/unload the driver by starting/stopping the corresponding +service using the `net` utility. net start test net stop test @@ -74,36 +92,48 @@ drivers**! You may also need to explicitly enable loading self-signed drivers on 64-bit versions of Windows. -One way is to use the `bcdedit` utility: +Using the `bcdedit` utility, execute bcdedit /set testsigning on -Then restart your computer and you should be all set! +and restart your computer. -## Debugging +## Remote debugging -You can debug a driver using WinDbg. +A driver can be debugged using WinDbg. To enable kernel debugging, you can use the `msconfig` utility (navigate to "Boot" -> "Advanced options..." and check "Debug") or the `bcdedit` utility: bcdedit /debug on bcdedit /dbgsettings serial debugport:1 baudrate:115200 -Restart your computer for these settings to take effect. +Then restart your computer for the new settings to take effect. -If a driver is loaded on a separate physical machine, you can connect to a -physical COM port from another host with WinDbg installed and enable kernel -debugging via "File" -> "Kernel Debug...". -You might need to restart the debuggee a couple of times in order to enter the -kernel debugging mode. +If a driver is loaded on a physical machine, you can connect to the COM port +specified in kernel debugging settings (#1 by default) with a proper cable +and enter the kernel debugging mode in WinDbg via "File" -> "Kernel Debug...". +You might need to restart the debuggee machine a couple of times in order to +enter the kernel debugging mode. -If a driver is running on a virtual machine, the conventional approach is to -expose a COM port via a named pipe. -You can then connect to the pipe from WinDbg installed on the host. -Refer to your virtualization software's documentation for more details. +If a driver is loaded on a virtual machine, the conventional approach is to +expose one of the guest OS's COM ports via a named pipe. +You can then connect to the pipe from a WinDbg instance on the host OS (via +"File" -> "Kernel Debug..."). +Refer to your virtualization software's documentation for details. -## Licensing +## Utilities + +A couple of usages examples are provided along with the drivers themselves. +For details, see [Utilities]. + +## License This project, including all of the files and their contents, is licensed under the terms of the MIT License. -See LICENSE.txt for details. +See [LICENSE.txt] for details. + + + +[Windows Driver Kit 7.1.0]: https://www.microsoft.com/en-us/download/details.aspx?id=11800 +[LICENSE.txt]: LICENSE.txt +[Utilities]: utils/README.md diff --git a/utils/README.md b/utils/README.md index c69617e..7dcf890 100644 --- a/utils/README.md +++ b/utils/README.md @@ -1,24 +1,30 @@ -# Service management utilities +# Driver utilities -Utilities used to manage (load, start, stop and unload) and communicate with -drivers via virtual devices. -Usage examples of some of the drivers in this repository are also included. +A few usage examples are provided along with the drivers. +Those include: -* [libservice](libservice) — a simple service management library. - Also includes means of communicating with a driver via virtual devices. -* [libnt_path_converter](libnt_path_converter) — - [nt_path_converter](../src/nt_path_converter) usage examples. -* [libtest](libtest) — [test](../src/test) usage examples. +* [libservice]: utilities to easily install/start/stop/uninstall drivers + (using Windows services), +* [libtest]: [test] driver usage examples, +* [libnt_path_converter]: [nt_path_converter] usage examples. ## Building -I've used the compiler shipped with Visual Studio Express 2013 with Update 4 -for Windows Desktop. +To build the utilities: -You can generate the solution windows7_drivers_utils.sln using CMake and build -it using Visual Studio. +1. generate the solution windows7_drivers_utils.sln using CMake, +2. build the solution using Visual Studio. -## Licensing +## License This project is licensed under the terms of the MIT License. -See [Licensing](../README.md#licensing) for details. +See [License] for details. + + + +[license]: ../README.md#license +[libservice]: libservice/README.md +[libtest]: libtest/README.md +[test]: ../src/test +[libnt_path_converter]: libnt_path_converter/README.md +[nt_path_converter]: ../src/nt_path_converter diff --git a/utils/libnt_path_converter/README.md b/utils/libnt_path_converter/README.md index e401aaa..43375e0 100644 --- a/utils/libnt_path_converter/README.md +++ b/utils/libnt_path_converter/README.md @@ -1,33 +1,36 @@ -# libnt_path_converter +# nt_path_converter driver utilities -[nt_path_converter](../../src/nt_path_converter) usage examples. +[nt_path_converter] driver usage examples. -## Usage +## Library -### libnt_path_converter.lib +[nt_path_converter] driver's virtual device is wrapped into a separate library +`libnt_path_converter` using [libservice]. +`#include <libnt_path_converter/all.hpp>` and link with +`libnt_path_converter.lib` to use the library. -Wraps `nt_path_converter`'s virtual device interface using -[libservice](../libservice). -Include the headers by `#include`ing `libnt_path_converter/all.hpp`, which -includes all the other header files. +## Utilities ### convert_nt_path.exe Usage: convert_nt_path.exe [NT_PATH...] Converts a NT-style path to a DOS-style path. -The NT namespace can be explored using the -[WinObj](https://technet.microsoft.com/en-us/library/bb896657.aspx) utility. -Usage example (assuming `nt_path_converter` is already loaded): +The NT namespace can be explored using the [WinObj] utility. +For example: > convert_nt_path.exe \Device\HarddiskVolume2\Windows C:\Windows -## Building +## See also -See [Building](../README.md#building). +* [Building] +* [License] -## Licensing -This project is licensed under the terms of the MIT License. -See [Licensing](../../README.md#licensing) for details. + +[building]: ../README.md#building +[license]: ../../README.md#license +[nt_path_converter]: ../../src/nt_path_converter +[libservice]: ../libservice/README.md +[WinObj]: https://technet.microsoft.com/en-us/library/bb896657.aspx diff --git a/utils/libservice/README.md b/utils/libservice/README.md index 8e25c2e..22c9388 100644 --- a/utils/libservice/README.md +++ b/utils/libservice/README.md @@ -1,39 +1,32 @@ -# libservice +# Service management utilities -Simple service management library and utilities. +Utilities to easily install/start/stop/uninstall drivers using Windows +services. -## Usage +## Library -### libservice.lib +`#include <libservice/all.hpp>` and link with `libservice.lib` to use the +library. -Include the headers by `#include`ing `libservice/all.hpp`, which includes all -the other header files. - -For service management usage examples, see the utilities descriptions below. - -For virtual device usage examples, refer e.g. to -[libnt_path_converter](../libnt_path_converter). +## Utilities ### install_service.exe Usage: install_service.exe NAME SYS_PATH Installs a driver as a service. -The service is started manually. The same as - sc create NAME type= kernel binPath= SYS_PATH + > sc create NAME type= kernel binPath= SYS_PATH ### start_service.exe Usage: start_service.exe NAME -Starts a service (loading the corresponding driver). +Starts the service `NAME` (loading the corresponding driver). The same as - net start NAME - -except that `start_service.exe` waits until the service is actually loaded. + > net start NAME ### stop_service.exe @@ -42,9 +35,7 @@ except that `start_service.exe` waits until the service is actually loaded. Stops the service `NAME` (unloading the corresponding driver). The same as - net stop NAME - -except that `stop_service.exe` waits until the service is actually stopped. + > net stop NAME ### uninstall_service.exe @@ -54,13 +45,14 @@ Uninstalls the service `NAME`, wiping the corresponding record from the registry. The same as - sc delete NAME + > sc delete NAME + +## See also -## Building +* [Building] +* [License] -See [Building](../README.md#building). -## Licensing -This project is licensed under the terms of the MIT License. -See [Licensing](../../README.md#licensing) for details. +[building]: ../README.md#building +[license]: ../../README.md#license diff --git a/utils/libtest/README.md b/utils/libtest/README.md index dae0cfe..4992849 100644 --- a/utils/libtest/README.md +++ b/utils/libtest/README.md @@ -1,22 +1,22 @@ -# libtest +# test driver utilities -[test](../../src/test) usage examples. +[test] driver usage examples. -## Usage +## Library -### libtest.lib +[test] driver's virtual device is wrapped into a separate library `libtest` +using [libservice]. +`#include <libtest/all.hpp>` and link with `libtest.lib` to use the library. -Wraps `test`'s virtual device interface using [libservice](../libservice). -Include the headers by `#include`ing `libtest/all.hpp`, which includes all the -other header files. +## Utilities ### exchange_ints.exe Usage: exchange_ints.exe N -Parses a given `unsigned int` and exchanges it with the value stored in -driver's memory. -Usage example (assuming `test` is already loaded): +Parses its argument as an `unsigned int` and exchanges it with the one stored +in [test] driver's memory. +For example: > exchange_ints.exe 1 42 @@ -27,11 +27,14 @@ Usage example (assuming `test` is already loaded): > exchange_ints.exe 100500 32 -## Building +## See also -See [Building](../README.md#building). +* [Building] +* [License] -## Licensing -This project is licensed under the terms of the MIT License. -See [Licensing](../../README.md#licensing) for details. + +[building]: ../README.md#building +[license]: ../../README.md#license +[test]: ../../src/test +[libservice]: ../libservice/README.md |