crosvm: Add documentation for crosvm_control

Adds documentation and best practices for the crosvm_control library.

BUG=b:188858559
TEST=cq

Change-Id: I8b03b9b78e72e0d47489d145476e33aa4310fef2
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/crosvm/+/3717537
Reviewed-by: Dennis Kempin <denniskempin@google.com>
Reviewed-by: Keiichi Watanabe <keiichiw@chromium.org>
Tested-by: kokoro <noreply+kokoro@google.com>
Commit-Queue: Kameron Lutes <kalutes@chromium.org>

docs/book/src/SUMMARY.md

@@ -8,6 +8,7 @@
   - [Custom Kernel / Rootfs](./running_crosvm/custom_kernel_rootfs.md)
   - [System Requirements](./running_crosvm/requirements.md)
   - [Features](./running_crosvm/features.md)
+  - [Programmatic Interaction](./running_crosvm/programmatic_interaction.md)
 - [Devices](./devices/index.md)
   - [Block](./devices/block.md)
   - [Network](./devices/net.md)
@@ -34,4 +35,4 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
-[API Documentation](./api.md)
+[Package Documentation](./package_documentation.md)

docs/book/src/api.md

@@ -1,4 +0,0 @@
-# API Document
-
-The API documentation generated by `cargo doc` is available
-[here](https://google.github.io/crosvm/doc/crosvm/).

docs/book/src/package_documentation.md

@@ -0,0 +1,4 @@
+# Package Documentation
+
+The package documentation generated by `cargo doc` is available
+[here](https://google.github.io/crosvm/doc/crosvm/).

docs/book/src/running_crosvm/programmatic_interaction.md

@@ -0,0 +1,36 @@
+# Programmatic Interaction Using the `crosvm_control` Library
+
+## Usage
+
+[`crosvm_control`](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/main/crosvm_control/src/lib.rs)
+provides a programmatic way to interface with crosvm as a substitute to the CLI.
+
+The library itself is written in Rust, but a C/C++ compatible header (`crosvm_control.h`) is
+generated during the crosvm build and emitted to the Rust `OUT_DIR`.
+([See the `build.rs`](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/main/crosvm_control/build.rs)
+script for more information).
+
+The best practice for using `crosvm_control` from your project is to exclusively use the
+`crosvm_control.h` generated by the crosvm build. This ensures that there will never be a runtime
+version mismatch between your project and crosvm. Additionally, this will allow for build-time
+checks against the crosvm API.
+
+During your project's build step, when building the crosvm dependency, the emitted
+`crosvm_control.h` should be installed to your project's include dir - overwriting the old version
+if present.
+
+## Changes
+
+As `crosvm_control` is a externally facing interface to crosvm, great care must be taken when
+updating the API surface. Any breaking change to a `crosvm_control` entrypoint must be handled the
+same way as a breaking change to the crosvm CLI.
+
+As a general rule, additive changes (such as adding new fields to the end of a struct, or adding a
+new API) are fine and should be integrated correctly with downstream projects so long as those
+projects follow the usage best practices. Changes that change the signature of any existing
+`crosvm_control` function will cause problems downstream and should be considered a breaking change.
+
+### (ChromeOS Developers Only)
+
+For ChromeOS, it is possible to integrate a breaking change from upstream crosvm, but it should be
+avoided if at all possible. [See here](../integration/chromeos.md#cq-depend) for more information.