kernel/hil/
crc.rs

Help
1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Interface for CRC computation.
6
7use crate::utilities::leasable_buffer::SubSliceMut;
8use crate::ErrorCode;
9
10/// Client for CRC algorithm implementations
11///
12/// Implement this trait and use [`Crc::set_client`] in order to
13/// receive callbacks from the CRC implementation.
14pub trait Client {
15    /// Called when the current data chunk has been processed by the
16    /// CRC engine. Further data may be supplied when this callback is
17    /// received.
18    fn input_done(&self, result: Result<(), ErrorCode>, buffer: SubSliceMut<'static, u8>);
19
20    /// Called when the CRC computation is finished.
21    fn crc_done(&self, result: Result<CrcOutput, ErrorCode>);
22}
23
24/// CRC algorithms
25///
26/// In all cases, input bytes are bit-reversed (i.e., consumed from LSB to MSB.)
27///
28/// Algorithms prefixed with `Sam4L` are native to that chip and thus require
29/// no software post-processing on platforms using it.
30///
31#[derive(Copy, Clone)]
32pub enum CrcAlgorithm {
33    /// Polynomial 0x04C11DB7, output reversed then inverted
34    /// ("CRC-32")
35    Crc32,
36    /// Polynomial 0x1EDC6F41, output reversed then inverted
37    /// ("CRC-32C" / "Castagnoli")
38    Crc32C,
39    /// Polynomial 0x1021, no output post-processing ("CRC-16-CCITT")
40    Crc16CCITT,
41}
42
43/// CRC output type
44///
45/// Individual CRC algorithms can have different output lengths. This
46/// type represents the different [`CrcAlgorithm`] outputs
47/// respectively.
48#[derive(Copy, Clone)]
49pub enum CrcOutput {
50    /// Output of [`CrcAlgorithm::Crc32`]
51    Crc32(u32),
52    /// Output of [`CrcAlgorithm::Crc32C`]
53    Crc32C(u32),
54    /// Output of [`CrcAlgorithm::Crc16CCITT`]
55    Crc16CCITT(u16),
56}
57
58impl CrcOutput {
59    pub fn algorithm(&self) -> CrcAlgorithm {
60        match self {
61            CrcOutput::Crc32(_) => CrcAlgorithm::Crc32,
62            CrcOutput::Crc32C(_) => CrcAlgorithm::Crc32C,
63            CrcOutput::Crc16CCITT(_) => CrcAlgorithm::Crc16CCITT,
64        }
65    }
66}
67
68pub trait Crc<'a> {
69    /// Set the client to be used for callbacks of the CRC
70    /// implementation.
71    fn set_client(&self, client: &'a dyn Client);
72    /// Check whether a given CRC algorithm is supported by a CRC
73    /// implementation.
74    ///
75    /// Returns true if the algorithm specified is supported.
76    fn algorithm_supported(&self, algorithm: CrcAlgorithm) -> bool;
77
78    /// Set the CRC algorithm to use.
79    ///
80    /// Calling this method may enable the CRC engine in case of a
81    /// physical unit.
82    ///
83    /// If the device is currently processing a chunk of data or
84    /// calculating a CRC, this operation will be refused, returning
85    /// [`ErrorCode::BUSY`]. If a CRC calculation currently has
86    /// pending data, it will be cancelled and the CRC engine's state
87    /// reset.
88    ///
89    /// [`ErrorCode::NOSUPPORT`] will be returned if the algorithm
90    /// requested is not supported. To non-invasively check whether a
91    /// given algorithm is supported by a CRC implementation, use
92    /// [`Crc::algorithm_supported`].
93    fn set_algorithm(&self, algorithm: CrcAlgorithm) -> Result<(), ErrorCode>;
94
95    /// Input chunked data into the CRC implementation.
96    ///
97    /// Calling this method may enable the CRC engine in case of a
98    /// physical unit.
99    ///
100    /// If [`Crc::set_algorithm`] has not been invoked before, this
101    /// method must return [`ErrorCode::RESERVE`].
102    ///
103    /// If the device is currently already processing a chunk of data
104    /// or calculating a CRC, [`ErrorCode::BUSY`] must be returned.
105    ///
106    /// After the chunk of data has been processed,
107    /// [`Client::input_done`] is called.
108    ///
109    /// The implementation may only read a part of the passed
110    /// [`SubSliceMut`]. It will return the bytes read and will
111    /// resize the returned [`SubSliceMut`] appropriately prior to
112    /// passing it back through [`Client::input_done`].
113    fn input(
114        &self,
115        data: SubSliceMut<'static, u8>,
116    ) -> Result<(), (ErrorCode, SubSliceMut<'static, u8>)>;
117
118    /// Request calculation of the CRC.
119    ///
120    /// Calling this method may enable the CRC engine in case of a
121    /// physical unit.
122    ///
123    /// If [`Crc::set_algorithm`] has not been invoked before, this
124    /// method must return [`ErrorCode::RESERVE`].
125    ///
126    /// If the device is currently processing a chunk of data or
127    /// calculating a CRC, [`ErrorCode::BUSY`] must be returned.
128    ///
129    /// After the CRC has been calculated, [`Client::crc_done`] is
130    /// called.
131    fn compute(&self) -> Result<(), ErrorCode>;
132
133    /// Disable the CRC unit until susequent calls to methods which
134    /// will enable the CRC unit again.
135    fn disable(&self);
136}
kernel/hil/crc.rs

kernel/hil/
crc.rs
