[hal doc] Describe wgpu-hal's validation principles.

wgpu-hal/src/lib.rs

@@ -149,6 +149,51 @@
  *
  * [Ii]: Instance::init
  *
+ * ## Validation is the user's responsibility, not `wgpu-hal`'s
+ *
+ * As much as possible, `wgpu-hal` traits place the burden of validation,
+ * resource tracking, and state tracking on the caller, not on the trait
+ * implementations themselves. Anything which can reasonably be handled in
+ * backend-independent code should be. A `wgpu_hal` backend's sole obligation is
+ * to provide portable behavior, and report conditions that the user can't
+ * reasonably anticipate, like device loss or running out of memory.
+ *
+ * The `wgpu` crate collection is intended for use in security-sensitive
+ * applications, like web browsers, where the API is available to untrusted
+ * code. This means that `wgpu-core`'s validation is not simply a service to
+ * developers, to be provided opportunistically when the performance costs are
+ * acceptable and the necessary data is ready at hand. Rather, `wgpu-core`'s
+ * validation must be exhaustive, to ensure that even malicious content cannot
+ * provoke and exploit undefined behavior in the platform's graphics API.
+ *
+ * Because graphics APIs' requirements are complex, the only practical way for
+ * `wgpu` to provide exhaustive validation is to comprehensively track the
+ * lifetime and state of all the resources in the system. Implementing this
+ * separately for each backend is infeasible. This effort is better spent making
+ * `wgpu-core` legible and trustworthy. Fortunately, the requirements are
+ * largely similar across the various platforms, so cross-platform validation is
+ * practical.
+ *
+ * Some backends have specific requirements that aren't practical to foist off
+ * on the `wgpu-hal` user. For example, properly managing macOS Objective-C or
+ * Microsoft COM reference counts is best handled by using appropriate pointer
+ * types within the backend.
+ *
+ * A desire for "defense in depth" may suggest performing additional validation
+ * in `wgpu-hal` when the opportunity arises, but this must be done with
+ * caution. New contributors infer the expectations their changes must meet by
+ * considering not just requirements made explicit in types, tests, assertions,
+ * and comments, but also those implicit in the surrounding code. If a
+ * contributor sees validation code in `wgpu-hal`, we must not let them
+ * conclude, "Oh, `wgpu-hal` checks for this, so `wgpu-core` needn't worry about
+ * it - that would be redundant!" The responsibility for exhaustive validation
+ * always rests with `wgpu-core`, regardless of what may or may not be checked
+ * in `wgpu-hal`.
+ *
+ * To this end, validation in `wgpu-hal` should report problems via the
+ * `unreachable!` macro, because problems detected at this stage indicate a bug
+ * in `wgpu-core`.
+ *
  * ## Debugging
  *
  * Most of the information on the wiki [Debugging wgpu Applications][wiki-debug]