Update User Guide

book/src/requirements/windows.md

@@ -2,11 +2,15 @@
 
 | Platform                  | *default*                                  | **fips**                                | bindgen required? |
 |---------------------------|--------------------------------------------|-----------------------------------------|-------------------|
-| `x86_64-pc-windows-msvc`  | C/C++ Compiler, CMake & NASM               | C/C++ Compiler, CMake, NASM, Go & Ninja | **_Yes_**         | 
-| `x86_64-pc-windows-gnu`   | C/C++ Compiler, CMake & NASM               | **Not Supported**                       | **_Yes_**         |
-| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported**                       | **_Yes_**         |
+| `x86_64-pc-windows-msvc`  | C/C++ Compiler, CMake & \*NASM             | C/C++ Compiler, CMake, NASM, Go & Ninja | No                | 
+| `x86_64-pc-windows-gnu`   | C/C++ Compiler, CMake & \*NASM             | **Not Supported**                       | No                |
+| `i686-pc-windows-msvc`    | C/C++ Compiler, CMake & NASM               | **Not Supported**                       | No                |
+| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported**                       | No                |
 | _Other_                   | **Not Supported**                          | **Not Supported**                       | N/A               |
 
+* The NASM assembler is recommended on `x86-64` platforms. NASM is required for `x86` and for "fips" builds. See the
+  [Prebuilt NASM objects](#prebuilt-nasm-objects) section below.
+
 ## C/C++ Compiler
 
 Use the following instructions to download **Visual Studio Build Tools 2017** or later.
@@ -36,7 +40,30 @@ Use the following instructions to download **Visual Studio Build Tools 2017** or
 2. Add the NASM installation directory to your PATH
     * `set PATH="C:\Program Files\NASM;%PATH%"`
 
-### No-assembly build
+### Use of prebuilt NASM objects
+
+For Windows x86 and x86-64, the AWS-LC assembly code requires NASM to build. On these platforms,
+we recommend that you install [the NASM assembler](https://www.nasm.us/). If a NASM assembler is
+found during the build process, then it *will* be used to compile the assembly files. However,
+if a NASM assembler is not found, then the (non-"fips") build may fail except in the following case:
+
+* You are building for `x86-64` and either:
+    * The `AWS_LC_SYS_PREBUILT_NASM` environment variable is found and has a value of "1" (or the value is empty); OR
+    * `AWS_LC_SYS_PREBUILT_NASM` is *not found* in the environment AND the "prebuilt-nasm" feature has been enabled.
+
+If the above cases apply, then our prebuilt NASM objects may be used for the build. To prevent our prebuilt NASM
+objects from being used, please install NASM and/or set `AWS_LC_SYS_PREBUILT_NASM=0` in your build environment to
+prevent their use.
+
+#### About prebuilt NASM objects
+
+Our prebuilt NASM objects are generated using the same automation that produces our pregenerated bindings. See our
+[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml).
+The prebuilt NASM objects are checked into our repository
+and are [available for inspection](https://github.com/aws/aws-lc-rs/tree/main/aws-lc-sys/builder/prebuilt-nasm).
+For each PR submitted,
+[our CI verifies](https://github.com/aws/aws-lc-rs/blob/8fb6869fc7bde92529a5cca40cf79513820984f7/.github/workflows/tests.yml#L209-L241)
+that the NASM objects newly built from source match the NASM objects currently in the repository.### No-assembly build
 
 It is possible to avoid the NASM requirement by setting the `AWS_LC_SYS_NO_ASM`/`AWS_LC_FIPS_SYS_NO_ASM` environment
 variables. However, this severely impacts performance and can only be used for un-optimized/debug builds. See the
@@ -50,7 +77,8 @@ notes in our [troubleshooting section](../resources.md#troubleshooting).
 
 ## Bindgen
 
-On most platforms, `bindgen` requires `libclang` or `llvm` package to be installed.
+Bindgen is not required for most Windows targets, but it can still be used if needed.
+Using `bindgen` requires a `libclang` or `llvm` package to be installed.
 See the [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html) page in
 [The bindgen User Guide] for instructions.
 

book/src/resources.md

@@ -20,6 +20,13 @@ future release. Please [contact us] about any bugs you find in our build process
   be used. This option is only available for unoptimized (i.e., `OPT_LEVEL = "0"` or "debug") builds.
   **WARNING**: Performance on most platforms is extremely limited by this option. Certain security
   properties, such as resistance to timing attacks, can only be provided when assembly code is used.
+* `AWS_LC_SYS_PREBUILT_NASM` -- value can be set to `1` to *allow* the build to use our prebuilt NASM objects.
+  The value can be set to `0` to *prevent* our prebuilt NASM objects from being used. See the section on
+  [Prebuilt NASM objects](requirements/windows.md#prebuilt-nasm-objects) for more information.
+* `AWS_LC_SYS_CFLAGS` -- if value is set, it will be used as the value of `CFLAGS` in the environment when the AWS-LC
+  build is performed.
+* `AWS_LC_SYS_C_STD` -- value can be set to determine the C standard used by the C compiler. It may be set to
+  either `99` for C99 or `11` for C11. On most platforms, C11 will be used by default.
 
 ## Links