diff options
Diffstat (limited to 'third_party/rust/half/README.md')
| -rw-r--r-- | third_party/rust/half/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/third_party/rust/half/README.md b/third_party/rust/half/README.md new file mode 100644 index 0000000000..ac6fa3c0ae --- /dev/null +++ b/third_party/rust/half/README.md @@ -0,0 +1,82 @@ +# `f16` and `bf16` floating point types for Rust +[](https://crates.io/crates/half/) [](https://docs.rs/half/)  [](https://github.com/starkat99/half-rs/actions/workflows/rust.yml) + +This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE +754-2008 standard [`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) +a.k.a `half` format, as well as a `bf16` type implementing the +[`bfloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) format. + +## Usage + +The `f16` and `bf16` types provides conversion operations as a normal Rust floating point type, but +since they are primarily leveraged for minimal floating point storage and most major hardware does +not implement them, all math operations are done as an `f32` type under the hood. Complex arithmetic +should manually convert to and from `f32` for better performance. + +This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support by +default so can easily be used in embedded code where a smaller float format is most useful. + +*Requires Rust 1.51 or greater.* If you need support for older versions of Rust, use versions 1.7.1 +and earlier of this crate. + +See the [crate documentation](https://docs.rs/half/) for more details. + +### Optional Features + +- **`serde`** - Implement `Serialize` and `Deserialize` traits for `f16` and `bf16`. This adds a + dependency on the [`serde`](https://crates.io/crates/serde) crate. + +- **`use-intrinsics`** - Use hardware intrinsics for `f16` and `bf16` conversions if available on + the compiler host target. By default, without this feature, conversions are done only in software, + which will be the fallback if the host target does not have hardware support. **Available only on + Rust nightly channel.** + +- **`alloc`** - Enable use of the [`alloc`](https://doc.rust-lang.org/alloc/) crate when not using + the `std` library. + + This enables the `vec` module, which contains zero-copy conversions for the `Vec` type. This + allows fast conversion between raw `Vec<u16>` bits and `Vec<f16>` or `Vec<bf16>` arrays, and vice + versa. + +- **`std`** - Enable features that depend on the Rust `std` library, including everything in the + `alloc` feature. + + Enabling the `std` feature enables runtime CPU feature detection when the `use-intrsincis` feature + is also enabled. + Without this feature detection, intrinsics are only used when compiler host target supports them. + +- **`num-traits`** - Enable `ToPrimitive`, `FromPrimitive`, `Num`, `Float`, `FloatCore` and + `Bounded` trait implementations from the [`num-traits`](https://crates.io/crates/num-traits) crate. + +- **`bytemuck`** - Enable `Zeroable` and `Pod` trait implementations from the + [`bytemuck`](https://crates.io/crates/bytemuck) crate. + +- **`zerocopy`** - Enable `AsBytes` and `FromBytes` trait implementations from the + [`zerocopy`](https://crates.io/crates/zerocopy) crate. + +### More Documentation + +- [Crate API Reference](https://docs.rs/half/) +- [Latest Changes](CHANGELOG.md) + +## License + +This library is distributed under the terms of either of: + +* [MIT License](LICENSES/MIT.txt) + ([http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) +* [Apache License, Version 2.0](LICENSES/Apache-2.0.txt) + ([http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)) + +at your option. + +This project is [REUSE-compliant](https://reuse.software/spec/). Copyrights are retained by their +contributors. Some files may include explicit copyright notices and/or license +[SPDX identifiers](https://spdx.dev/ids/). For full authorship information, see the version control +history. + +### Contributing + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the +work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any +additional terms or conditions. |