Diff: drivers/MbedCRC.h

Revision:

0:38ceb79fef03

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/drivers/MbedCRC.h	Wed Nov 28 15:10:15 2018 +0000
@@ -0,0 +1,562 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2018 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef MBED_CRC_API_H
+#define MBED_CRC_API_H
+
+#include "drivers/TableCRC.h"
+#include "hal/crc_api.h"
+#include "platform/mbed_assert.h"
+#include "platform/SingletonPtr.h"
+#include "platform/PlatformMutex.h"
+
+/* This is invalid warning from the compiler for below section of code
+if ((width < 8) && (NULL == _crc_table)) {
+    p_crc = (uint32_t)(p_crc << (8 - width));
+}
+Compiler warns of the shift operation with width as it is width=(std::uint8_t),
+but we check for ( width < 8) before performing shift, so it should not be an issue.
+*/
+#if defined ( __CC_ARM )
+#pragma diag_suppress 62  // Shift count is negative
+#elif defined ( __GNUC__ )
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wshift-count-negative"
+#elif defined (__ICCARM__)
+#pragma diag_suppress=Pe062  // Shift count is negative
+#endif
+
+namespace mbed {
+/** \addtogroup drivers */
+/** @{*/
+
+/** CRC object provides CRC generation through hardware/software
+ *
+ *  ROM polynomial tables for supported polynomials (:: crc_polynomial_t) will be used for
+ *  software CRC computation, if ROM tables are not available then CRC is computed runtime
+ *  bit by bit for all data input.
+ *  @note Synchronization level: Thread safe
+ *
+ *  @tparam  polynomial CRC polynomial value in hex
+ *  @tparam  width CRC polynomial width
+ *
+ * Example: Compute CRC data
+ * @code
+ *
+ *  #include "mbed.h"
+ *
+ *  int main() {
+ *      MbedCRC<POLY_32BIT_ANSI, 32> ct;
+ *
+ *      char  test[] = "123456789";
+ *      uint32_t crc = 0;
+ *
+ *      printf("\nPolynomial = 0x%lx  Width = %d \n", ct.get_polynomial(), ct.get_width());
+ *
+ *      ct.compute((void *)test, strlen((const char*)test), &crc);
+ *
+ *      printf("The CRC of data \"123456789\" is : 0x%lx\n", crc);
+ *      return 0;
+ *  }
+ * @endcode
+ * Example: Compute CRC with data available in parts
+ * @code
+ *
+ *  #include "mbed.h"
+ *  int main() {
+ *      MbedCRC<POLY_32BIT_ANSI, 32> ct;
+ *
+ *      char  test[] = "123456789";
+ *      uint32_t crc = 0;
+ *
+ *      printf("\nPolynomial = 0x%lx  Width = %d \n", ct.get_polynomial(), ct.get_width());
+ *      ct.compute_partial_start(&crc);
+ *      ct.compute_partial((void *)&test, 4, &crc);
+ *      ct.compute_partial((void *)&test[4], 5, &crc);
+ *      ct.compute_partial_stop(&crc);
+ *      printf("The CRC of data \"123456789\" is : 0x%lx\n", crc);
+ *      return 0;
+ *  }
+ * @endcode
+ * @ingroup drivers
+ */
+
+extern SingletonPtr<PlatformMutex> mbed_crc_mutex;
+
+template <uint32_t polynomial = POLY_32BIT_ANSI, uint8_t width = 32>
+class MbedCRC {
+
+public:
+    enum CrcMode
+    {
+#ifdef DEVICE_CRC
+        HARDWARE = 0,
+#endif
+        TABLE = 1,
+        BITWISE
+    };
+
+    typedef uint64_t crc_data_size_t;
+
+    /** Lifetime of CRC object
+     *
+     *  @param  initial_xor  Inital value/seed to Xor
+     *  @param  final_xor  Final Xor value
+     *  @param  reflect_data
+     *  @param  reflect_remainder
+     *  @note   Default constructor without any arguments is valid only for supported CRC polynomials. :: crc_polynomial_t
+     *          MbedCRC <POLY_7BIT_SD, 7> ct; --- Valid POLY_7BIT_SD
+     *          MbedCRC <0x1021, 16> ct; --- Valid POLY_16BIT_CCITT
+     *          MbedCRC <POLY_16BIT_CCITT, 32> ct; --- Invalid, compilation error
+     *          MbedCRC <POLY_16BIT_CCITT, 32> ct (i,f,rd,rr) Constructor can be used for not supported polynomials
+     *          MbedCRC<POLY_16BIT_CCITT, 16> sd(0, 0, false, false); Constructor can also be used for supported
+     *             polynomials with different intial/final/reflect values
+     *
+     */
+    MbedCRC(uint32_t initial_xor, uint32_t final_xor, bool reflect_data, bool reflect_remainder) :
+        _initial_value(initial_xor), _final_xor(final_xor), _reflect_data(reflect_data),
+        _reflect_remainder(reflect_remainder)
+    {
+        mbed_crc_ctor();
+    }
+    MbedCRC();
+    virtual ~MbedCRC()
+    {
+        // Do nothing
+    }
+
+    /** Compute CRC for the data input
+     *  Compute CRC performs the initialization, computation and collection of
+     *  final CRC.
+     *
+     *  @param  buffer  Data bytes
+     *  @param  size  Size of data
+     *  @param  crc  CRC is the output value
+     *  @return  0 on success, negative error code on failure
+     */
+    int32_t compute(void *buffer, crc_data_size_t size, uint32_t *crc)
+    {
+        MBED_ASSERT(crc != NULL);
+        int32_t status = 0;
+
+        status = compute_partial_start(crc);
+        if (0 != status) {
+            unlock();
+            return status;
+        }
+
+        status = compute_partial(buffer, size, crc);
+        if (0 != status) {
+            unlock();
+            return status;
+        }
+
+        status = compute_partial_stop(crc);
+        if (0 != status) {
+           *crc = 0;
+        }
+
+        return status;
+
+    }
+
+    /** Compute partial CRC for the data input.
+     *
+     *  CRC data if not available fully, CRC can be computed in parts with available data.
+     *
+     *  In case of hardware, intermediate values and states are saved by hardware. Mutex
+     *  locking is used to serialize access to hardware CRC.
+     *
+     *  In case of software CRC, previous CRC output should be passed as argument to the
+     *  current compute_partial call. Please note the intermediate CRC value is maintained by
+     *  application and not the driver.
+     *
+     *  @pre: Call `compute_partial_start` to start the partial CRC calculation.
+     *  @post: Call `compute_partial_stop` to get the final CRC value.
+     *
+     *  @param  buffer  Data bytes
+     *  @param  size  Size of data
+     *  @param  crc  CRC value is intermediate CRC value filled by API.
+     *  @return  0  on success or a negative error code on failure
+     *  @note: CRC as output in compute_partial is not final CRC value, call `compute_partial_stop`
+     *         to get final correct CRC value.
+     */
+    int32_t compute_partial(void *buffer, crc_data_size_t size, uint32_t *crc)
+    {
+        int32_t status = 0;
+
+        switch (_mode) {
+#ifdef DEVICE_CRC
+            case HARDWARE:
+                hal_crc_compute_partial((uint8_t *)buffer, size);
+                *crc = 0;
+                break;
+#endif
+            case TABLE:
+                status = table_compute_partial(buffer, size, crc);
+                break;
+            case BITWISE:
+                status = bitwise_compute_partial(buffer, size, crc);
+                break;
+            default:
+                status = -1;
+                break;
+        }
+
+        return status;
+    }
+
+    /** Compute partial start, indicate start of partial computation.
+     *
+     *  This API should be called before performing any partial computation
+     *  with compute_partial API.
+     *
+     *  @param  crc  Initial CRC value set by the API
+     *  @return  0  on success or a negative in case of failure
+     *  @note: CRC is an out parameter and must be reused with compute_partial
+     *         and `compute_partial_stop` without any modifications in application.
+     */
+    int32_t compute_partial_start(uint32_t *crc)
+    {
+        MBED_ASSERT(crc != NULL);
+
+#ifdef DEVICE_CRC
+        if (_mode == HARDWARE) {
+            lock();
+            crc_mbed_config_t config;
+            config.polynomial  = polynomial;
+            config.width       = width;
+            config.initial_xor = _initial_value;
+            config.final_xor   = _final_xor;
+            config.reflect_in  = _reflect_data;
+            config.reflect_out = _reflect_remainder;
+
+            hal_crc_compute_partial_start(&config);
+        }
+#endif
+
+        *crc = _initial_value;
+        return 0;
+    }
+
+    /** Get the final CRC value of partial computation.
+     *
+     *  CRC value available in partial computation is not correct CRC, as some
+     *  algorithms require remainder to be reflected and final value to be XORed
+     *  This API is used to perform final computation to get correct CRC value.
+     *
+     *  @param crc  CRC result
+     *  @return  0  on success or a negative in case of failure.
+     */
+    int32_t compute_partial_stop(uint32_t *crc)
+    {
+        MBED_ASSERT(crc != NULL);
+
+#ifdef DEVICE_CRC
+        if (_mode == HARDWARE) {
+            *crc = hal_crc_get_result();
+            unlock();
+            return 0;
+        }
+#endif
+        uint32_t p_crc = *crc;
+        if ((width < 8) && (NULL == _crc_table)) {
+            p_crc = (uint32_t)(p_crc << (8 - width));
+        }
+        // Optimized algorithm for 32BitANSI does not need additional reflect_remainder
+        if ((TABLE == _mode) && (POLY_32BIT_REV_ANSI == polynomial)) {
+            *crc = (p_crc ^ _final_xor) & get_crc_mask();
+        } else {
+            *crc = (reflect_remainder(p_crc) ^ _final_xor) & get_crc_mask();
+        }
+        unlock();
+        return 0;
+    }
+
+    /** Get the current CRC polynomial.
+     *
+     * @return  Polynomial value
+     */
+    uint32_t get_polynomial(void) const
+    {
+        return polynomial;
+    }
+
+    /** Get the current CRC width
+     *
+     * @return  CRC width
+     */
+    uint8_t get_width(void) const
+    {
+        return width;
+    }
+
+private:
+    uint32_t _initial_value;
+    uint32_t _final_xor;
+    bool _reflect_data;
+    bool _reflect_remainder;
+    uint32_t *_crc_table;
+    CrcMode _mode;
+
+    /** Acquire exclusive access to CRC hardware/software.
+     */
+     void lock()
+    {
+#ifdef DEVICE_CRC
+        if (_mode == HARDWARE) {
+            mbed_crc_mutex->lock();
+        }
+#endif
+    }
+
+    /** Release exclusive access to CRC hardware/software.
+     */
+    virtual void unlock()
+    {
+#ifdef DEVICE_CRC
+        if (_mode == HARDWARE) {
+            mbed_crc_mutex->unlock();
+        }
+#endif
+    }
+
+    /** Get the current CRC data size.
+     *
+     * @return  CRC data size in bytes
+     */
+    uint8_t get_data_size(void) const
+    {
+        return (width <= 8 ? 1 : (width <= 16 ? 2 : 4));
+    }
+
+    /** Get the top bit of current CRC.
+     *
+     * @return  Top bit is set high for respective data width of current CRC
+     *          Top bit for CRC width less then 8 bits will be set as 8th bit.
+     */
+    uint32_t get_top_bit(void) const
+    {
+        return (width < 8 ? (1u << 7) : (uint32_t)(1ul << (width - 1)));
+    }
+
+    /** Get the CRC data mask.
+     *
+     * @return  CRC data mask is generated based on current CRC width
+     */
+    uint32_t get_crc_mask(void) const
+    {
+        return (width < 8 ? ((1u << 8) - 1) : (uint32_t)((uint64_t)(1ull << width) - 1));
+    }
+
+    /** Final value of CRC is reflected.
+     *
+     * @param  data final crc value, which should be reflected
+     * @return  Reflected CRC value
+     */
+    uint32_t reflect_remainder(uint32_t data) const
+    {
+        if (_reflect_remainder) {
+            uint32_t reflection = 0x0;
+            uint8_t const nBits = (width < 8 ? 8 : width);
+
+            for (uint8_t bit = 0; bit < nBits; ++bit) {
+                if (data & 0x01) {
+                    reflection |= (1 << ((nBits - 1) - bit));
+                }
+                data = (data >> 1);
+            }
+            return (reflection);
+        } else {
+            return data;
+        }
+    }
+
+    /** Data bytes are reflected.
+     *
+     * @param  data value to be reflected
+     * @return  Reflected data value
+     */
+    uint32_t reflect_bytes(uint32_t data) const
+    {
+        if (_reflect_data) {
+            uint32_t reflection = 0x0;
+
+            for (uint8_t bit = 0; bit < 8; ++bit) {
+                if (data & 0x01) {
+                    reflection |= (1 << (7 - bit));
+                }
+                data = (data >> 1);
+            }
+            return (reflection);
+        } else {
+            return data;
+        }
+    }
+
+    /** Bitwise CRC computation.
+     *
+     * @param  buffer  data buffer
+     * @param  size  size of the data
+     * @param  crc  CRC value is filled in, but the value is not the final
+     * @return  0  on success or a negative error code on failure
+     */
+    int32_t bitwise_compute_partial(const void *buffer, crc_data_size_t size, uint32_t *crc) const
+    {
+        MBED_ASSERT(crc != NULL);
+
+        const uint8_t *data = static_cast<const uint8_t *>(buffer);
+        uint32_t p_crc = *crc;
+
+        if (width < 8) {
+            uint8_t data_byte;
+            for (crc_data_size_t byte = 0; byte < size; byte++) {
+                data_byte = reflect_bytes(data[byte]);
+                for (uint8_t bit = 8; bit > 0; --bit) {
+                    p_crc <<= 1;
+                    if ((data_byte ^ p_crc) & get_top_bit()) {
+                        p_crc ^= polynomial;
+                    }
+                    data_byte <<= 1;
+                }
+            }
+        } else {
+            for (crc_data_size_t byte = 0; byte < size; byte++) {
+                p_crc ^= (reflect_bytes(data[byte]) << (width - 8));
+
+                // Perform modulo-2 division, a bit at a time
+                for (uint8_t bit = 8; bit > 0; --bit) {
+                    if (p_crc & get_top_bit()) {
+                        p_crc = (p_crc << 1) ^ polynomial;
+                    } else {
+                        p_crc = (p_crc << 1);
+                    }
+                }
+            }
+        }
+        *crc = p_crc & get_crc_mask();
+        return 0;
+    }
+
+    /** CRC computation using ROM tables.
+    *
+    * @param  buffer  data buffer
+    * @param  size  size of the data
+    * @param  crc  CRC value is filled in, but the value is not the final
+    * @return  0  on success or a negative error code on failure
+    */
+    int32_t table_compute_partial(const void *buffer, crc_data_size_t size, uint32_t *crc) const
+    {
+        MBED_ASSERT(crc != NULL);
+
+        const uint8_t *data = static_cast<const uint8_t *>(buffer);
+        uint32_t p_crc = *crc;
+        uint8_t data_byte = 0;
+
+        if (width <= 8) {
+            uint8_t *crc_table = (uint8_t *)_crc_table;
+            for (crc_data_size_t byte = 0; byte < size; byte++) {
+                data_byte = reflect_bytes(data[byte]) ^ p_crc;
+                p_crc = crc_table[data_byte];
+            }
+        } else if (width <= 16) {
+            uint16_t *crc_table = (uint16_t *)_crc_table;
+            for (crc_data_size_t byte = 0; byte < size; byte++) {
+                data_byte = reflect_bytes(data[byte]) ^ (p_crc >> (width - 8));
+                p_crc = crc_table[data_byte] ^ (p_crc << 8);
+            }
+        } else {
+            uint32_t *crc_table = (uint32_t *)_crc_table;
+            if (POLY_32BIT_REV_ANSI == polynomial) {
+                for (crc_data_size_t i = 0; i < size; i++) {
+                    p_crc = (p_crc >> 4) ^ crc_table[(p_crc ^ (data[i] >> 0)) & 0xf];
+                    p_crc = (p_crc >> 4) ^ crc_table[(p_crc ^ (data[i] >> 4)) & 0xf];
+                }
+            }
+            else {
+                for (crc_data_size_t byte = 0; byte < size; byte++) {
+                    data_byte = reflect_bytes(data[byte]) ^ (p_crc >> (width - 8));
+                    p_crc = crc_table[data_byte] ^ (p_crc << 8);
+                }
+            }
+        }
+        *crc = p_crc & get_crc_mask();
+        return 0;
+    }
+
+    /** Constructor init called from all specialized cases of constructor.
+     *  Note: All construtor common code should be in this function.
+     */
+    void mbed_crc_ctor(void)
+    {
+        MBED_STATIC_ASSERT(width <= 32, "Max 32-bit CRC supported");
+
+#ifdef DEVICE_CRC
+        if (POLY_32BIT_REV_ANSI == polynomial) {
+            _crc_table = (uint32_t *)Table_CRC_32bit_Rev_ANSI;
+            _mode = TABLE;
+            return;
+        }
+        crc_mbed_config_t config;
+        config.polynomial  = polynomial;
+        config.width       = width;
+        config.initial_xor = _initial_value;
+        config.final_xor   = _final_xor;
+        config.reflect_in  = _reflect_data;
+        config.reflect_out = _reflect_remainder;
+
+        if (hal_crc_is_supported(&config)) {
+            _mode = HARDWARE;
+            return;
+        }
+#endif
+
+        switch (polynomial) {
+            case POLY_32BIT_ANSI:
+                _crc_table = (uint32_t *)Table_CRC_32bit_ANSI;
+                break;
+            case POLY_32BIT_REV_ANSI:
+                _crc_table = (uint32_t *)Table_CRC_32bit_Rev_ANSI;
+                break;
+            case POLY_8BIT_CCITT:
+                _crc_table = (uint32_t *)Table_CRC_8bit_CCITT;
+                break;
+            case POLY_7BIT_SD:
+                _crc_table = (uint32_t *)Table_CRC_7Bit_SD;
+                break;
+            case POLY_16BIT_CCITT:
+                _crc_table = (uint32_t *)Table_CRC_16bit_CCITT;
+                break;
+            case POLY_16BIT_IBM:
+                _crc_table = (uint32_t *)Table_CRC_16bit_IBM;
+                break;
+            default:
+                _crc_table = NULL;
+                break;
+        }
+        _mode = (_crc_table != NULL) ? TABLE : BITWISE;
+    }
+};
+
+#if   defined ( __CC_ARM )
+#elif defined ( __GNUC__ )
+#pragma GCC diagnostic pop
+#elif defined (__ICCARM__)
+#endif
+
+/** @}*/
+} // namespace mbed
+
+#endif