README updates

5 files changed, 157 insertions, 123 deletions

diff --git a/README.md b/README.md
index 62a5f72..421435e 100644
--- a/README.md
+++ b/README.md
@@ -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