Add PVF module documentation (#6293)

* Add PVF module documentation

TODO (once the PRs land):

- [ ] Document executor parametrization.

- [ ] Document CPU time measurement of timeouts.

* Update node/core/pvf/src/lib.rs

Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>

* Clarify meaning of PVF acronym

* Move PVF doc to implementer's guide

* Clean up implementer's guide a bit

* Add page for PVF types

* pvf: Better separation between crate docs and implementer's guide

* ci: Add "prevalidating" to the dictionary

* ig: Remove types/chain.md

The types contained therein did not exist and the file was not referenced
anywhere.

Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>

polkadot/node/core/pvf/src/executor_intf.rs

@@ -96,7 +96,7 @@ pub fn prevalidate(code: &[u8]) -> Result<RuntimeBlob, sc_executor_common::error
 }
 
 /// Runs preparation on the given runtime blob. If successful, it returns a serialized compiled
-/// artifact which can then be used to pass into [`execute`] after writing it to the disk.
+/// artifact which can then be used to pass into `Executor::execute` after writing it to the disk.
 pub fn prepare(blob: RuntimeBlob) -> Result<Vec<u8>, sc_executor_common::error::WasmError> {
 	sc_executor_wasmtime::prepare_runtime_artifact(blob, &CONFIG.semantics)
 }

polkadot/node/core/pvf/src/lib.rs

@@ -16,18 +16,27 @@
 
 #![warn(missing_docs)]
 
-//! A crate that implements PVF validation host.
+//! A crate that implements the PVF validation host.
+//!
+//! For more background, refer to the Implementer's Guide: [PVF
+//! Pre-checking](https://paritytech.github.io/polkadot/book/pvf-prechecking.html) and [Candidate
+//! Validation](https://paritytech.github.io/polkadot/book/node/utility/candidate-validation.html#pvf-host).
+//!
+//! # Entrypoint
 //!
 //! This crate provides a simple API. You first [`start`] the validation host, which gives you the
 //! [handle][`ValidationHost`] and the future you need to poll.
 //!
-//! Then using the handle the client can send two types of requests:
+//! Then using the handle the client can send three types of requests:
 //!
-//! (a) PVF execution. This accepts the PVF [`params`][`polkadot_parachain::primitives::ValidationParams`]
+//! (a) PVF pre-checking. This takes the PVF [code][`Pvf`] and tries to prepare it (verify and
+//! compile) in order to pre-check its validity.
+//!
+//! (b) PVF execution. This accepts the PVF [`params`][`polkadot_parachain::primitives::ValidationParams`]
 //!     and the PVF [code][`Pvf`], prepares (verifies and compiles) the code, and then executes PVF
 //!     with the `params`.
 //!
-//! (b) Heads up. This request allows to signal that the given PVF may be needed soon and that it
+//! (c) Heads up. This request allows to signal that the given PVF may be needed soon and that it
 //!     should be prepared for execution.
 //!
 //! The preparation results are cached for some time after they either used or was signaled in heads up.
@@ -39,7 +48,7 @@
 //! PVF execution requests can specify the [priority][`Priority`] with which the given request should
 //! be handled. Different priority levels have different effects. This is discussed below.
 //!
-//! Preparation started by a heads up signal always starts in with the background priority. If there
+//! Preparation started by a heads up signal always starts with the background priority. If there
 //! is already a request for that PVF preparation under way the priority is inherited. If after heads
 //! up, a new PVF execution request comes in with a higher priority, then the original task's priority
 //! will be adjusted to match the new one if it's larger.
@@ -48,6 +57,8 @@
 //!
 //! # Under the hood
 //!
+//! ## The flow
+//!
 //! Under the hood, the validation host is built using a bunch of communicating processes, not
 //! dissimilar to actors. Each of such "processes" is a future task that contains an event loop that
 //! processes incoming messages, potentially delegating sub-tasks to other "processes".
@@ -55,11 +66,13 @@
 //! Two of these processes are queues. The first one is for preparation jobs and the second one is for
 //! execution. Both of the queues are backed by separate pools of workers of different kind.
 //!
-//! Preparation workers handle preparation requests by preverifying and instrumenting PVF wasm code,
+//! Preparation workers handle preparation requests by prevalidating and instrumenting PVF wasm code,
 //! and then passing it into the compiler, to prepare the artifact.
 //!
-//! Artifact is a final product of preparation. If the preparation succeeded, then the artifact will
-//! contain the compiled code usable for quick execution by a worker later on.
+//! ## Artifacts
+//!
+//! An artifact is the final product of preparation. If the preparation succeeded, then the artifact
+//! will contain the compiled code usable for quick execution by a worker later on.
 //!
 //! If the preparation failed, then the worker will still write the artifact with the error message.
 //! We save the artifact with the error so that we don't try to prepare the artifacts that are broken
@@ -68,12 +81,14 @@
 //! The artifact is saved on disk and is also tracked by an in memory table. This in memory table
 //! doesn't contain the artifact contents though, only a flag that the given artifact is compiled.
 //!
+//! A pruning task will run at a fixed interval of time. This task will remove all artifacts that
+//! weren't used or received a heads up signal for a while.
+//!
+//!	## Execution
+//!
 //! The execute workers will be fed by the requests from the execution queue, which is basically a
 //! combination of a path to the compiled artifact and the
 //! [`params`][`polkadot_parachain::primitives::ValidationParams`].
-//!
-//! Each fixed interval of time a pruning task will run. This task will remove all artifacts that
-//! weren't used or received a heads up signal for a while.
 
 mod artifacts;
 mod error;

polkadot/node/core/pvf/src/priority.rs

@@ -24,7 +24,7 @@ pub enum Priority {
 	Normal,
 	/// This priority is used for requests that are required to be processed as soon as possible.
 	///
-	/// For example, backing is on critical path and require execution as soon as possible.
+	/// For example, backing is on a critical path and requires execution as soon as possible.
 	Critical,
 }