Debian Codegraph @

.cargo/vendor/zerocopy/README.md

raw
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.