add documentation about feature flags

1 files changed, 23 insertions, 5 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 06e2502..8985c2e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -83,6 +83,24 @@
 //! let plaintext = aez.decrypt(b"nonce", &[b"bar"], 16, &cipher);
 //! assert!(plaintext.is_none());
 //! ```
+//!
+//! # Feature flags & compilation hints
+//!
+//! * Enable feature `simd` (requires nightly due to the `portable_simd` Rust feature) to speed up
+//!   encryption and decryption by using SIMD instructions (if available).
+//! * Use `target-cpu=native` (e.g. by setting `RUSTFLAGS=-Ctarget-cpu=native`) to make the
+//!   compiler emit vectorized AES instructions (if available). This can speed up
+//!   encryption/decryption at the cost of producing less portable code.
+//!
+//! On my machine, this produces the following results (for the `encrypt_inplace/2048` benchmark):
+//!
+//! | Compilation setup        | Throughput   | Speedup  |
+//! |--------------------------|--------------|----------|
+//! | baseline                 | 488.78 MiB/s |          |
+//! | +simd                    | 967.91 MiB/s | +98.187% |
+//! | target-cpu=native        | 2.0062 GiB/s | +314.67% |
+//! | +simd, target-cpu=native | 3.3272 GiB/s | +592.01% |
+//! | `aez` crate              | 4.8996 GiB/s |          |
 
 use constant_time_eq::constant_time_eq;
 
@@ -316,7 +334,7 @@ fn encrypt(aez: &Aez, nonce: &[u8], ad: &[&[u8]], tau: u32, buffer: &mut [u8]) {
             tweaks_vec = vec![&tau_bytes, nonce];
             tweaks_vec.extend(ad);
             &tweaks_vec
-        },
+        }
     };
     assert!(buffer.len() >= tau as usize);
     if buffer.len() == tau as usize {
@@ -498,11 +516,11 @@ fn cipher_aez_core(mode: Mode, aez: &Aez, tweaks: Tweak, message: &mut [u8]) {
         Mode::Encipher => {
             s_x = m_x ^ delta ^ x ^ e(0, 1, aez, m_y);
             s_y = m_y ^ e(-1, 1, aez, s_x);
-        },
+        }
         Mode::Decipher => {
             s_x = m_x ^ delta ^ x ^ e(0, 2, aez, m_y);
             s_y = m_y ^ e(-1, 2, aez, s_x);
-        },
+        }
     }
     let s = s_x ^ s_y;
 
@@ -548,11 +566,11 @@ fn cipher_aez_core(mode: Mode, aez: &Aez, tweaks: Tweak, message: &mut [u8]) {
         Mode::Encipher => {
             c_y = s_x ^ e(-1, 2, aez, s_y);
             c_x = s_y ^ delta ^ y ^ e(0, 2, aez, c_y);
-        },
+        }
         Mode::Decipher => {
             c_y = s_x ^ e(-1, 1, aez, s_y);
             c_x = s_y ^ delta ^ y ^ e(0, 1, aez, c_y);
-        },
+        }
     }
 
     blocks.set_m_u(c_u);