| 1 |
<!-- Copyright 2024 The Fuchsia Authors |
| 2 |
|
| 3 |
Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0 |
| 4 |
<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT |
| 5 |
license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. |
| 6 |
This file may not be copied, modified, or distributed except according to |
| 7 |
those terms. |
| 8 |
|
| 9 |
WARNING: DO NOT EDIT THIS FILE. It is generated automatically. Edits should be |
| 10 |
made in the doc comment on `src/lib.rs` or in `tools/generate-readme`. |
| 11 |
--> |
| 12 |
|
| 13 |
# zerocopy |
| 14 |
|
| 15 |
***<span style="font-size: 140%">Fast, safe, <span |
| 16 |
style="color:red;">compile error</span>. Pick two.</span>*** |
| 17 |
|
| 18 |
Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe` |
| 19 |
so you don't have to. |
| 20 |
|
| 21 |
*For an overview of what's changed from zerocopy 0.7, check out our [release |
| 22 |
notes][release-notes], which include a step-by-step upgrading guide.* |
| 23 |
|
| 24 |
*Have questions? Need more out of zerocopy? Submit a [customer request |
| 25 |
issue][customer-request-issue] or ask the maintainers on |
| 26 |
[GitHub][github-q-a] or [Discord][discord]!* |
| 27 |
|
| 28 |
[customer-request-issue]: https://github.com/google/zerocopy/issues/new/choose |
| 29 |
[release-notes]: https://github.com/google/zerocopy/discussions/1680 |
| 30 |
[github-q-a]: https://github.com/google/zerocopy/discussions/categories/q-a |
| 31 |
[discord]: https://discord.gg/MAvWH2R6zk |
| 32 |
|
| 33 |
## Overview |
| 34 |
|
| 35 |
###### Conversion Traits |
| 36 |
|
| 37 |
Zerocopy provides four derivable traits for zero-cost conversions: |
| 38 |
- `TryFromBytes` indicates that a type may safely be converted from |
| 39 |
certain byte sequences (conditional on runtime checks) |
| 40 |
- `FromZeros` indicates that a sequence of zero bytes represents a valid |
| 41 |
instance of a type |
| 42 |
- `FromBytes` indicates that a type may safely be converted from an |
| 43 |
arbitrary byte sequence |
| 44 |
- `IntoBytes` indicates that a type may safely be converted *to* a byte |
| 45 |
sequence |
| 46 |
|
| 47 |
These traits support sized types, slices, and [slice DSTs][slice-dsts]. |
| 48 |
|
| 49 |
[slice-dsts]: KnownLayout#dynamically-sized-types |
| 50 |
|
| 51 |
###### Marker Traits |
| 52 |
|
| 53 |
Zerocopy provides three derivable marker traits that do not provide any |
| 54 |
functionality themselves, but are required to call certain methods provided |
| 55 |
by the conversion traits: |
| 56 |
- `KnownLayout` indicates that zerocopy can reason about certain layout |
| 57 |
qualities of a type |
| 58 |
- `Immutable` indicates that a type is free from interior mutability, |
| 59 |
except by ownership or an exclusive (`&mut`) borrow |
| 60 |
- `Unaligned` indicates that a type's alignment requirement is 1 |
| 61 |
|
| 62 |
You should generally derive these marker traits whenever possible. |
| 63 |
|
| 64 |
###### Conversion Macros |
| 65 |
|
| 66 |
Zerocopy provides six macros for safe casting between types: |
| 67 |
|
| 68 |
- (`try_`[try_transmute])`transmute` (conditionally) converts a value of |
| 69 |
one type to a value of another type of the same size |
| 70 |
- (`try_`[try_transmute_mut])`transmute_mut` (conditionally) converts a |
| 71 |
mutable reference of one type to a mutable reference of another type of |
| 72 |
the same size |
| 73 |
- (`try_`[try_transmute_ref])`transmute_ref` (conditionally) converts a |
| 74 |
mutable or immutable reference of one type to an immutable reference of |
| 75 |
another type of the same size |
| 76 |
|
| 77 |
These macros perform *compile-time* size and alignment checks, meaning that |
| 78 |
unconditional casts have zero cost at runtime. Conditional casts do not need |
| 79 |
to validate size or alignment runtime, but do need to validate contents. |
| 80 |
|
| 81 |
These macros cannot be used in generic contexts. For generic conversions, |
| 82 |
use the methods defined by the [conversion traits](#conversion-traits). |
| 83 |
|
| 84 |
###### Byteorder-Aware Numerics |
| 85 |
|
| 86 |
Zerocopy provides byte-order aware integer types that support these |
| 87 |
conversions; see the `byteorder` module. These types are especially useful |
| 88 |
for network parsing. |
| 89 |
|
| 90 |
## Cargo Features |
| 91 |
|
| 92 |
- **`alloc`** |
| 93 |
By default, `zerocopy` is `no_std`. When the `alloc` feature is enabled, |
| 94 |
the `alloc` crate is added as a dependency, and some allocation-related |
| 95 |
functionality is added. |
| 96 |
|
| 97 |
- **`std`** |
| 98 |
By default, `zerocopy` is `no_std`. When the `std` feature is enabled, the |
| 99 |
`std` crate is added as a dependency (ie, `no_std` is disabled), and |
| 100 |
support for some `std` types is added. `std` implies `alloc`. |
| 101 |
|
| 102 |
- **`derive`** |
| 103 |
Provides derives for the core marker traits via the `zerocopy-derive` |
| 104 |
crate. These derives are re-exported from `zerocopy`, so it is not |
| 105 |
necessary to depend on `zerocopy-derive` directly. |
| 106 |
|
| 107 |
However, you may experience better compile times if you instead directly |
| 108 |
depend on both `zerocopy` and `zerocopy-derive` in your `Cargo.toml`, |
| 109 |
since doing so will allow Rust to compile these crates in parallel. To do |
| 110 |
so, do *not* enable the `derive` feature, and list both dependencies in |
| 111 |
your `Cargo.toml` with the same leading non-zero version number; e.g: |
| 112 |
|
| 113 |
```toml |
| 114 |
[dependencies] |
| 115 |
zerocopy = "0.X" |
| 116 |
zerocopy-derive = "0.X" |
| 117 |
``` |
| 118 |
|
| 119 |
To avoid the risk of [duplicate import errors][duplicate-import-errors] if |
| 120 |
one of your dependencies enables zerocopy's `derive` feature, import |
| 121 |
derives as `use zerocopy_derive::*` rather than by name (e.g., `use |
| 122 |
zerocopy_derive::FromBytes`). |
| 123 |
|
| 124 |
- **`simd`** |
| 125 |
When the `simd` feature is enabled, `FromZeros`, `FromBytes`, and |
| 126 |
`IntoBytes` impls are emitted for all stable SIMD types which exist on the |
| 127 |
target platform. Note that the layout of SIMD types is not yet stabilized, |
| 128 |
so these impls may be removed in the future if layout changes make them |
| 129 |
invalid. For more information, see the Unsafe Code Guidelines Reference |
| 130 |
page on the [layout of packed SIMD vectors][simd-layout]. |
| 131 |
|
| 132 |
- **`simd-nightly`** |
| 133 |
Enables the `simd` feature and adds support for SIMD types which are only |
| 134 |
available on nightly. Since these types are unstable, support for any type |
| 135 |
may be removed at any point in the future. |
| 136 |
|
| 137 |
- **`float-nightly`** |
| 138 |
Adds support for the unstable `f16` and `f128` types. These types are |
| 139 |
not yet fully implemented and may not be supported on all platforms. |
| 140 |
|
| 141 |
[duplicate-import-errors]: https://github.com/google/zerocopy/issues/1587 |
| 142 |
[simd-layout]: https://rust-lang.github.io/unsafe-code-guidelines/layout/packed-simd-vectors.html |
| 143 |
|
| 144 |
## Security Ethos |
| 145 |
|
| 146 |
Zerocopy is expressly designed for use in security-critical contexts. We |
| 147 |
strive to ensure that that zerocopy code is sound under Rust's current |
| 148 |
memory model, and *any future memory model*. We ensure this by: |
| 149 |
- **...not 'guessing' about Rust's semantics.** |
| 150 |
We annotate `unsafe` code with a precise rationale for its soundness that |
| 151 |
cites a relevant section of Rust's official documentation. When Rust's |
| 152 |
documented semantics are unclear, we work with the Rust Operational |
| 153 |
Semantics Team to clarify Rust's documentation. |
| 154 |
- **...rigorously testing our implementation.** |
| 155 |
We run tests using [Miri], ensuring that zerocopy is sound across a wide |
| 156 |
array of supported target platforms of varying endianness and pointer |
| 157 |
width, and across both current and experimental memory models of Rust. |
| 158 |
- **...formally proving the correctness of our implementation.** |
| 159 |
We apply formal verification tools like [Kani][kani] to prove zerocopy's |
| 160 |
correctness. |
| 161 |
|
| 162 |
For more information, see our full [soundness policy]. |
| 163 |
|
| 164 |
[Miri]: https://github.com/rust-lang/miri |
| 165 |
[Kani]: https://github.com/model-checking/kani |
| 166 |
[soundness policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#soundness |
| 167 |
|
| 168 |
## Relationship to Project Safe Transmute |
| 169 |
|
| 170 |
[Project Safe Transmute] is an official initiative of the Rust Project to |
| 171 |
develop language-level support for safer transmutation. The Project consults |
| 172 |
with crates like zerocopy to identify aspects of safer transmutation that |
| 173 |
would benefit from compiler support, and has developed an [experimental, |
| 174 |
compiler-supported analysis][mcp-transmutability] which determines whether, |
| 175 |
for a given type, any value of that type may be soundly transmuted into |
| 176 |
another type. Once this functionality is sufficiently mature, zerocopy |
| 177 |
intends to replace its internal transmutability analysis (implemented by our |
| 178 |
custom derives) with the compiler-supported one. This change will likely be |
| 179 |
an implementation detail that is invisible to zerocopy's users. |
| 180 |
|
| 181 |
Project Safe Transmute will not replace the need for most of zerocopy's |
| 182 |
higher-level abstractions. The experimental compiler analysis is a tool for |
| 183 |
checking the soundness of `unsafe` code, not a tool to avoid writing |
| 184 |
`unsafe` code altogether. For the foreseeable future, crates like zerocopy |
| 185 |
will still be required in order to provide higher-level abstractions on top |
| 186 |
of the building block provided by Project Safe Transmute. |
| 187 |
|
| 188 |
[Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html |
| 189 |
[mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411 |
| 190 |
|
| 191 |
## MSRV |
| 192 |
|
| 193 |
See our [MSRV policy]. |
| 194 |
|
| 195 |
[MSRV policy]: https://github.com/google/zerocopy/blob/main/POLICIES.md#msrv |
| 196 |
|
| 197 |
## Changelog |
| 198 |
|
| 199 |
Zerocopy uses [GitHub Releases]. |
| 200 |
|
| 201 |
[GitHub Releases]: https://github.com/google/zerocopy/releases |
| 202 |
|
| 203 |
## Thanks |
| 204 |
|
| 205 |
Zerocopy is maintained by engineers at Google and Amazon with help from |
| 206 |
[many wonderful contributors][contributors]. Thank you to everyone who has |
| 207 |
lent a hand in making Rust a little more secure! |
| 208 |
|
| 209 |
[contributors]: https://github.com/google/zerocopy/graphs/contributors |
| 210 |
|
| 211 |
## Disclaimer |
| 212 |
|
| 213 |
Disclaimer: Zerocopy is not an officially supported Google product. |