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