Write page about zerocopy.

Cargo.toml

@@ -2,4 +2,5 @@
 members = [
   "i18n-helpers",
   "src/exercises",
+  "src/bare-metal/useful-crates/zerocopy-example",
 ]

src/SUMMARY.md

@@ -267,8 +267,8 @@
   - [Logging](bare-metal/aps/logging.md)
     - [Using it](bare-metal/aps/logging/using.md)
   - [Other projects](bare-metal/aps/other-projects.md)
-- [Useful crates]()
-  - [zerocopy]()
+- [Useful crates](bare-metal/useful-crates.md)
+  - [zerocopy](bare-metal/useful-crates/zerocopy.md)
   - [aarch64_paging]()
   - [buddy_system_allocator]()
   - [tinyvec]()

src/bare-metal/useful-crates.md

@@ -0,0 +1,3 @@
+# Useful crates
+
+We'll go over a few crates which solve some common problems in bare-metal programming.

src/bare-metal/useful-crates/zerocopy-example/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "zerocopy-example"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+zerocopy = "0.6.1"

src/bare-metal/useful-crates/zerocopy-example/src/main.rs

@@ -0,0 +1,46 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// ANCHOR: main
+use zerocopy::AsBytes;
+
+#[repr(u32)]
+#[derive(AsBytes, Debug, Default)]
+enum RequestType {
+    #[default]
+    In = 0,
+    Out = 1,
+    Flush = 4,
+}
+
+#[repr(C)]
+#[derive(AsBytes, Debug, Default)]
+struct VirtioBlockRequest {
+    request_type: RequestType,
+    reserved: u32,
+    sector: u64,
+}
+
+fn main() {
+    let request = VirtioBlockRequest {
+        request_type: RequestType::Flush,
+        sector: 42,
+        ..Default::default()
+    };
+
+    assert_eq!(
+        request.as_bytes(),
+        &[4, 0, 0, 0, 0, 0, 0, 0, 42, 0, 0, 0, 0, 0, 0, 0]
+    );
+}

src/bare-metal/useful-crates/zerocopy.md

@@ -0,0 +1,23 @@
+# `zerocopy`
+
+The [`zerocopy`][1] crate (from Fuchsia) provides traits and macros for safely converting between
+byte sequences and other types.
+
+```rust,editable,compile_fail
+{{#include zerocopy-example/src/main.rs:main}}
+```
+
+This is not suitable for MMIO (as it doesn't use volatile reads and writes), but can be useful for
+working with structures shared with hardware e.g. by DMA, or sent over some external interface.
+
+<details>
+
+* `FromBytes` can be implemented for types for which any byte pattern is valid, and so can safely be
+  converted from an untrusted sequence of bytes.
+* Attempting to derive `FromBytes` for these types would fail, because `RequestType` doesn't use all
+  possible u32 values as discriminants, so not all byte patterns are valid.
+* `zerocopy::byteorder` has types for byte-order aware numeric primitives.
+
+</details>
+
+[1]: https://docs.rs/zerocopy/