esp_idf_hal/
rom.rs

1//! ESP ROM libraries
2//!
3//! Safe abstractions to the additional libraries provided in the ESP's
4//! read-only memory.
5
6pub mod crc {
7    //! Cyclic Redundancy Check
8    //!
9    //! These are safe abstractions to the CRC functions in the ESP32 ROM.
10    //! Some chips may not include all of these functions so they will be compiled
11    //! into the program binary in those cases.
12    //!
13    //! # Parameters
14    //!
15    //! The ROM provides the following polynomials for each CRC width:
16    //!
17    //! | CRC Width | Polynomial  |
18    //! | --------- | ----------- |
19    //! | CRC-8     | 0x07        |
20    //! | CRC-16    | 0x1021      |
21    //! | CRC-32    | 0x04c11db7  |
22    //!
23    //! The "big-endian" `*_be()` functions are left-shifting algorithms to be used
24    //! when input and output reflection are **not** needed. If input and output
25    //! reflection **are** needed, the right-shifting "little-endian" `*_le()`
26    //! functions should be used.
27    //!
28    //! These functions are designed to compute a CRC over a single buffer or as an
29    //! ongoing calculation over multiple buffers. To do this, the initial value
30    //! passed in and the final value returned are one's complemented.
31    //!
32    //! ```
33    //! // CRC-32/MPEG-2
34    //! const CRC_INITIAL = 0xffffffff; // "init" or "xorin" of all ones
35    //! let mut crc = crc32_be(!CRC_INITIAL, &data0); // start
36    //! crc = crc32_be(crc, &data1);
37    //! crc = !crc32_be(crc, &data2); // finish
38    //! ```
39    //!
40    //! # Examples
41    //!
42    //! A catalogue of these parameters can be found at
43    //! <https://reveng.sourceforge.io/crc-catalogue/all.htm>
44    //!
45    //! CRC-32/ISO-HDLC poly=0x04c11db7 init=0xffffffff refin=true refout=true xorout=0xffffffff
46    //!
47    //! ```
48    //! let crc = crc32_le(!0xffffffff, &data);
49    //! ```
50    //!
51    //! CRC-32/BZIP2 poly=0x04c11db7 init=0xffffffff refin=false refout=false xorout=0xffffffff
52    //!
53    //! ```
54    //! let crc = crc32_be(!0xffffffff, &data);
55    //! ```
56    //!
57    //! CRC-32/MPEG-2 poly=0x04c11db7 init=0xffffffff refin=false refout=false xorout=0x00000000
58    //!
59    //! ```
60    //! let crc = !crc32_be(!0xffffffff, &data);
61    //! ```
62    //!
63    //! CRC-32/CKSUM poly=0x04c11db7 init=0x00000000 refin=false refout=false xorout=0xffffffff
64    //!
65    //! ```
66    //! let crc = crc32_be(!0, &data);
67    //! ```
68    //!
69    //! CRC-16/KERMIT poly=0x1021 init=0x0000 refin=true refout=true xorout=0x0000
70    //!
71    //! ```
72    //! let crc = !crc16_le(!0, &data);
73    //! ```
74
75    use esp_idf_sys::*;
76
77    // SAFETY: These functions are all implemented as table lookups. No locking is
78    // needed to access them, they are all referentially transparent, and the size
79    // and alignment of `usize` and `u32` are identical on all ESP32 chips.
80
81    /// Right-shifting CRC-32 with polynomial 0x04c11db7
82    #[inline(always)]
83    pub fn crc32_le(crc: u32, buf: &[u8]) -> u32 {
84        unsafe { esp_rom_crc32_le(crc, buf.as_ptr(), buf.len() as u32) }
85    }
86
87    /// Left-shifting CRC-32 with polynomial 0x04c11db7
88    #[inline(always)]
89    pub fn crc32_be(crc: u32, buf: &[u8]) -> u32 {
90        unsafe { esp_rom_crc32_be(crc, buf.as_ptr(), buf.len() as u32) }
91    }
92
93    /// Right-shifting CRC-16 with polynomial 0x1021
94    #[inline(always)]
95    pub fn crc16_le(crc: u16, buf: &[u8]) -> u16 {
96        unsafe { esp_rom_crc16_le(crc, buf.as_ptr(), buf.len() as u32) }
97    }
98
99    /// Left-shifting CRC-16 with polynomial 0x1021
100    #[inline(always)]
101    pub fn crc16_be(crc: u16, buf: &[u8]) -> u16 {
102        unsafe { esp_rom_crc16_be(crc, buf.as_ptr(), buf.len() as u32) }
103    }
104
105    /// Right-shifting CRC-8 with polynomial 0x07
106    #[inline(always)]
107    pub fn crc8_le(crc: u8, buf: &[u8]) -> u8 {
108        unsafe { esp_rom_crc8_le(crc, buf.as_ptr(), buf.len() as u32) }
109    }
110
111    /// Left-shifting CRC-8 with polynomial 0x07
112    #[inline(always)]
113    pub fn crc8_be(crc: u8, buf: &[u8]) -> u8 {
114        unsafe { esp_rom_crc8_be(crc, buf.as_ptr(), buf.len() as u32) }
115    }
116}
esp_idf_hal/rom.rs

esp_idf_hal/
rom.rs
