├── .gitignore ├── Cargo.toml ├── LICENSE ├── README.md └── src └── lib.rs /.gitignore: -------------------------------------------------------------------------------- 1 | # Generated by Cargo 2 | # will have compiled files and executables 3 | /target/ 4 | 5 | # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries 6 | # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html 7 | Cargo.lock 8 | 9 | # These are backup files generated by rustfmt 10 | **/*.rs.bk 11 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "coin" 3 | version = "0.1.0" 4 | edition = "2021" 5 | authors = ["Tim McNamara "] 6 | license = "CC0" 7 | description = "A data type for representing Boolean values that is resistant to bit flips." 8 | 9 | # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html 10 | 11 | [dependencies] 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # coin: a radiation-safe Boolean 2 | 3 | A `Coin` is data type for representing Boolean values that is resistant to bit 4 | flips. Prefer `Coin` to `bool` in safety-critical environments with long-lived 5 | variables, such as global variables. 6 | 7 | A standard `bool` is truth-biased, because `false` matches a single bit pattern 8 | (all zeros). A single bit flip invalidates the value. `Coin` counts the number 9 | of bits to determine its truth value. When 4 or more bits are 1, the value is 10 | interpreted as `true`. `Coin` can tolerate 3 bit flips per byte before an 11 | incorrect value is returned. 12 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | use std::cell::Cell; 2 | use std::{convert::From, hash::Hash}; 3 | // TODO: impl Deref to improve ergonomics 4 | 5 | /// A bit flip resistant Boolean type 6 | /// 7 | /// Prefer `Coin` to `bool` in safety-critical environments with long-lived 8 | /// variables, such as global variables. `Coin` uses the same space as `bool`. 9 | /// 10 | /// `Coin` imposes a small runtime and moderate ergonomic costs when being 11 | /// used in places where you would normally use `bool`. Therefore, you'll 12 | /// generally convert it to a standard `bool` as a local variable. 13 | /// 14 | /// ## Examples 15 | /// 16 | /// To use `Coin` in an `if` expression, it must first be converted to `bool`. 17 | /// 18 | /// ``` 19 | /// # use coin::Coin; 20 | /// # fn main() { 21 | /// let c = Coin::from(true); 22 | /// 23 | /// if c.to_bool() { 24 | /// println!("Clunky, but effective."); 25 | /// } 26 | /// # } 27 | /// ``` 28 | /// 29 | /// ## Warnings 30 | /// 31 | /// Rust's `true` is converted to numeric types, such as `i32`, it becomes 1. 32 | /// This bit pattern (`0b0000_0001`) is considered to be `false` within the 33 | /// internal representation that's used by `Coin`. 34 | /// 35 | /// ``` 36 | /// # use coin::Coin; 37 | /// # fn main() { 38 | /// let c = Coin::from(true); 39 | /// let one = i32::from(c.to_bool()); 40 | /// assert_eq!(Coin::from(one == 1), c); 41 | /// # } 42 | /// ``` 43 | /// 44 | /// ## Background and implementation notes 45 | /// 46 | /// A standard `bool` is truth-biased, because `false` matches a single 47 | /// bit pattern (all zeros). A single bit flip invalidates the value. 48 | /// 49 | /// `Coin` counts the number of bits to determine its truth value. When 50 | /// 4 or more bits are 1, the value is interpreted as `true`. `Coin` can 51 | /// tolerate 3 bit flips per byte before an incorrect value is returned. 52 | /// 53 | /// For a more thorough introduction, see the talk "Software Security in the Presence of 54 | /// Faults" by Peter Gutmann (PDF ) 55 | /// (talk recording ). 56 | #[derive(Debug, Clone)] 57 | pub struct Coin(Cell); 58 | 59 | impl Coin { 60 | #[inline] 61 | fn truthy() -> Self { 62 | Coin(Cell::new(u8::MAX)) 63 | } 64 | 65 | #[inline] 66 | fn falsey() -> Self { 67 | Coin(Cell::new(u8::MIN)) 68 | } 69 | 70 | #[inline(always)] 71 | pub fn to_bool(&self) -> bool { 72 | let val = self.0.get(); 73 | val.count_ones() >= val.count_zeros() // call twice to avoid baking a constant (4) into the binary 74 | // TODO: what if a bit in the opcode flips? 75 | } 76 | 77 | fn degauss(&self) { 78 | // TODO: what if bits in these constants accumulate errors? 79 | let fresh_bits = match self.to_bool() { 80 | true => u8::MAX, 81 | false => u8::MIN, 82 | }; 83 | 84 | self.0.set(fresh_bits); 85 | } 86 | } 87 | 88 | impl Hash for Coin { 89 | fn hash(&self, state: &mut H) { 90 | self.degauss(); 91 | self.to_bool().hash(state); 92 | } 93 | } 94 | 95 | impl Eq for Coin {} 96 | 97 | impl PartialEq for Coin { 98 | #[inline(always)] 99 | fn eq(&self, other: &Self) -> bool { 100 | self.degauss(); 101 | other.degauss(); 102 | self.to_bool() == other.to_bool() 103 | } 104 | } 105 | 106 | impl Ord for Coin { 107 | fn cmp(&self, other: &Self) -> std::cmp::Ordering { 108 | self.degauss(); 109 | other.degauss(); 110 | self.to_bool().cmp(&other.to_bool()) 111 | } 112 | } 113 | 114 | impl PartialOrd for Coin { 115 | fn partial_cmp(&self, other: &Self) -> Option { 116 | self.degauss(); 117 | other.degauss(); 118 | self.to_bool().partial_cmp(&other.to_bool()) 119 | } 120 | } 121 | 122 | impl From<&Coin> for bool { 123 | #[inline(always)] 124 | fn from(c: &Coin) -> Self { 125 | c.to_bool() 126 | } 127 | } 128 | 129 | impl From for bool { 130 | #[inline(always)] 131 | fn from(c: Coin) -> Self { 132 | c.to_bool() 133 | } 134 | } 135 | 136 | impl From for Coin { 137 | #[inline(always)] 138 | fn from(b: bool) -> Self { 139 | match b { 140 | true => Coin::truthy(), 141 | false => Coin::falsey(), 142 | } 143 | } 144 | } 145 | 146 | 147 | #[cfg(test)] 148 | mod tests { 149 | use super::Coin; 150 | 151 | #[test] 152 | fn one_bit_flip() { 153 | let coin = Coin::from(true); 154 | coin.0.set(0b1111_1011); 155 | assert!(coin.to_bool()); 156 | } 157 | 158 | #[test] 159 | fn two_bits_flipped() { 160 | let coin = Coin::from(true); 161 | coin.0.set(0b1101_0011); 162 | assert!(coin.to_bool()); 163 | } 164 | 165 | #[test] 166 | fn three_bits_flipped() { 167 | let coin = Coin::from(true); 168 | coin.0.set(0b1101_0011); 169 | assert!(coin.to_bool()); 170 | } 171 | 172 | #[test] 173 | fn four_bits_flipped() { 174 | let coin = Coin::from(true); 175 | coin.0.set(0b1100_0011); 176 | assert!(coin.to_bool()); 177 | } 178 | 179 | #[test] 180 | fn five_bits_flipped() { 181 | let coin = Coin::from(true); 182 | coin.0.set(0b1000_0011); 183 | assert!(!coin.to_bool()); 184 | } 185 | } 186 | --------------------------------------------------------------------------------