CRC.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!*****************************************************************************
 *  @file       CRC.h
 *  @brief      CRC driver interface
 *
 *  @anchor ti_drivers_CRC_Overview
 *  # Overview #
 *
 *  The CRC driver interface provides device independent APIs, data types,
 *  and macros. The CRC header file should be included in an application as
 *  follows:
 *  @code
 *  #include <ti/drivers/CRC.h>
 *  @endcode
 *
 *  The Cyclic Redundancy Check (CRC) driver is a generic driver that supports
 *  calculating a variety of standard CRC codes on blocks of input data.
 *
 *  <hr>
 *  @anchor ti_drivers_CRC_Usage
 *  # Usage #
 *  To calculate the CRC of a block of available data, an application should call:
 *    - CRC_init(): Initialize the CRC driver.
 *    - CRC_Params_init():  Initialize a default #CRC_Params structure.
 *    - CRC_open(): Open an instance of the CRC driver, passing the
 *      initialized parameters, or NULL, and an index (described later).
 *    - CRC_calculateFull(): Calculate the CRC of a data block.
 *    - CRC_close(): De-initialize the CRC instance.
 *
 *  If the data is only available in noncontiguous memory or is being made
 *  available in blocks (e.g. over UART) then the addData and finalise methods
 *  may be used to calculate the CRC of individual blocks.
 *
 *  The CRC driver only accepts data lengths that are a multiple of the CRC size.
 *  If asked to CRC 7 bytes with a 4-byte CRC, it will throw an error. Similarly,
 *  if padding bytes are required for a particular application this must be handled
 *  by the caller.
 *
 *  @anchor ti_drivers_CRC_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_CRC_Synopsis_Code
 *  @code
 *  CRC_Handle      handle;
 *  CRC_Params      params;
 *  int_fast16_t    status;
 *  uint32_t        result;
 *  uint8_t         source[NUM_BYTES];
 *
 *  CRC_init();  // Initialize the CRC driver
 *
 *  CRC_Params_init(&params);     // Initialize CRC parameters
 *  params.returnBehavior = CRC_RETURN_BEHAVIOR_BLOCKING;
 *
 *  params.polynomial = CRC_POLYNOMIAL_CRC_16_CCITT;
 *  params.dataSize = CRC_DATA_SIZE_32BIT;
 *  params.seed = 0xFFFF;
 *  params.byteSwapInput = CRC_BYTESWAP_UNCHANGED;
 *
 *  handle = CRC_open(CONFIG_CRC0, &params);
 *  if (handle == NULL) {
 *      while (1);  // CRC_open() failed
 *  }
 *
 *  // Fill in source
 *
 *  status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
 *
 *  if (status != CRC_STATUS_SUCCESS) {
 *      // Error with parameters, or CRC resource was unavailable
 *      while (1);
 *  }
 *  @endcode
 *
 *  More details on usage are provided in the following sections.
 *
 *  <hr>
 *  @anchor ti_drivers_CRC_Examples
 *  # Examples
 *
 *  @li @ref ti_drivers_CRC_Examples_open "Opening a CRC instance"
 *  @li @ref ti_drivers_CRC_Examples_calculateFull "Calculating a full check value"
 *  @li @ref ti_drivers_CRC_Examples_calculatePartial "Partial check calculations"
 *
 *  @anchor ti_drivers_CRC_Examples_open
 *  ## Opening a CRC instance
 *  After initializing the CRC driver by calling CRC_init(), the application
 *  can open a CRC instance by calling CRC_open().  This function
 *  takes an index into the CRC_config[] array, and a CRC parameters data
 *  structure. The CRC instance is specified by the index of the CRC in
 *  CRC_config[]. Only one CRC index can be used at a time;
 *  calling CRC_open() a second time with the same index previously
 *  passed to CRC_open() will result in an error. You can,
 *  though, re-use the index if the instance is closed via CRC_close().
 *
 *  If no CRC_Params structure is passed to CRC_open(), default values are
 *  used. If the open call is successful, it returns a non-NULL value.
 *
 *  @code
 *  CRC_Handle handle;
 *  CRC_Params params;
 *
 *  // Initialize the CRC driver
 *  CRC_init();
 *
 *  // Initialize optional CRC parameters for CALLBACK mode
 *  CRC_Params_init(&params);
 *  params.returnBehavior = CRC_RETURN_BEHAVIOR_CALLBACK;
 *  params.callbackFxn = myCallbackFunction;
 *
 *  handle = CRC_open(CONFIG_CRC0, &params);
 *  if (handle == NULL) {
 *      // CRC_open() failed
 *      while (1);
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_CRC_Examples_calculateFull
 *  ## Using the calculateFull API
 *
 *  ### CRC-8-CCITT without data processing
 *  An 8-bit CRC with no data processing options. Note that the
 *  default POLLING mode uses the CPU to move data so will not
 *  allow the device to enter standby in low-power applications.
 *
 *  @code
 *  CRC_Handle      handle;
 *  int_fast16_t    status;
 *  uint8_t         source[NUM_BYTES];
 *  uint8_t         result;
 *
 *  // Initialize the CRC driver
 *  CRC_init();
 *
 *  // The defaults are set to a POLLING mode 8-bit CRC with seed 0xFF
 *  // We can pass NULL instead of a Params struct to make use of this
 *  handle = CRC_open(CONFIG_CRC0, NULL);
 *
 *  if (handle == NULL) {
 *      while (1);  // CRC_open() failed
 *  }
 *
 *  status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
 *
 *  if (status != CRC_STATUS_SUCCESS) {
 *      // Error with parameters, or CRC resource was unavailable
 *      while (1);
 *  }
 *  @endcode
 *
 *  ### CRC-32-IEEE with endianness reversal
 *  A 32-bit CRC with data processing options, in BLOCKING mode.
 *
 *  @code
 *  CRC_Handle      handle;
 *  CRC_Params      params;
 *  int_fast16_t    status;
 *  uint32_t        result;
 *  uint8_t         source[NUM_BYTES];
 *
 *  CRC_init();  // Initialize the CRC driver
 *
 *  CRC_Params_init(&params);     // Initialize CRC parameters
 *  params.returnBehavior = CRC_RETURN_BEHAVIOR_BLOCKING;
 *
 *  params.byteSwapInput = CRC_BYTESWAP_BYTES_AND_HALF_WORDS;
 *  params.polynomial = CRC_POLYNOMIAL_CRC_32_IEEE;
 *  params.dataSize = CRC_DATA_SIZE_32BIT;
 *  params.seed = 0xFFFFFFFF;
 *
 *  handle = CRC_open(CONFIG_CRC0, &params);
 *
 *  if (handle == NULL) {
 *      while (1);  // CRC_open() failed
 *  }
 *
 *  // Obtain data for the source buffer
 *
 *  status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
 *
 *  if (status != CRC_STATUS_SUCCESS) {
 *      // Error with parameters, or CRC resource was unavailable
 *      while (1);
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_CRC_Examples_calculatePartial
 *  ## Using the addData API
 *
 *  It may be desirable to use the CRC to calculate over blocks of data that
 *  are available at different times or non-contiguous in memory. A
 *  block-by-block API is available to do this. The following code calculates
 *  the CRC of two separate arrays as though they were concatenated.
 *
 *  @code
 *  CRC_Handle      handle;
 *  CRC_Params      params;
 *  int_fast16_t    status;
 *  uint32_t        result;
 *
 *  uint32_t         sourceA [NUM_BYTES] = { ... };
 *  uint32_t         sourceB [NUM_BYTES] = { ... };
 *
 *  CRC_init();
 *  CRC_Params_init(&params);
 *
 *  params.byteSwapInput = CRC_BYTESWAP_UNCHANGED;
 *  params.polynomial = CRC_POLYNOMIAL_CRC_32C;
 *  params.dataSize = CRC_DATA_SIZE_32BIT;
 *  params.seed = 0xFFFFFFFF;
 *
 *  handle = CRC_open(CONFIG_CRC0, &params);
 *
 *  if (handle == NULL) {
 *      while (1);  // CRC_open() failed
 *  }
 *
 *  status = CRC_addData(handle, sourceA, NUM_BYTES);
 *
 *  if (status != CRC_STATUS_SUCCESS) {
 *      // CRC resource was unavailable
 *      while (1);
 *  }
 *
 *  status = CRC_addData(handle, sourceB, NUM_BYTES);
 *
 *  if (status != CRC_STATUS_SUCCESS) {
 *      // CRC resource was unavailable
 *      while (1);
 *  }
 *
 *  CRC_finalize(handle, &result);
 *  @endcode
 *
 *******************************************************************************
 */

#ifndef ti_drivers_CRC__include
#define ti_drivers_CRC__include

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

#define CRC_STATUS_RESERVED                 (-32)

#define CRC_STATUS_SUCCESS                  (0)

#define CRC_STATUS_ERROR                    (-1)

#define CRC_STATUS_RESOURCE_UNAVAILABLE     (-2)

#define CRC_STATUS_OPERATION_NOT_SUPPORTED  (-3)

#define CRC_STATUS_LEFTOVER_BYTES_PRESENT   (-4)

typedef struct {
    void               *object;
    void         const *hwAttrs;
} CRC_Config;

typedef CRC_Config *CRC_Handle;

typedef enum {
    CRC_RETURN_BEHAVIOR_CALLBACK = 1,   
    CRC_RETURN_BEHAVIOR_BLOCKING = 2,   
    CRC_RETURN_BEHAVIOR_POLLING  = 4,   
} CRC_ReturnBehavior;

/* Not all polynomials are supported on all implementations; see the device specific
 * header files for details. OPERATION_NOT_SUPPORTED will be returned if an
 * unsupported polynomial is requested.
 *
 * Texas Instruments does not provide advice on polynomial suitability. The
 * availability of polynomials in this driver or on a particular device does
 * not imply fitness for any particular task. If highly reliable error
 * detection capabilities are required, please consult a domain expert
 * before choosing a polynomial.
 */
typedef enum {
    CRC_POLYNOMIAL_CRC_8_CCITT,
    CRC_POLYNOMIAL_CRC_16_CCITT,
    CRC_POLYNOMIAL_CRC_16_IBM,
    CRC_POLYNOMIAL_CRC_32_IEEE,
    CRC_POLYNOMIAL_CRC_32C,
    CRC_POLYNOMIAL_CRC_32_IO_LINK,

    CRC_POLYNOMIAL_CRC_TCP,

    CRC_POLYNOMIAL_CUSTOM_PROGRAMMABLE,
} CRC_Polynomial;

typedef enum {
    CRC_BYTESWAP_UNCHANGED,             /* A B C D -> A B C D */
    CRC_BYTESWAP_HALF_WORDS,            /* A B C D -> C D A B */
    CRC_BYTESWAP_BYTES_IN_HALF_WORDS,   /* A B C D -> B A D C */
    CRC_BYTESWAP_BYTES_AND_HALF_WORDS,  /* A B C D -> D C B A */
} CRC_ByteSwap;

typedef enum {
    CRC_DATA_SIZE_8BIT,
    CRC_DATA_SIZE_16BIT,
    CRC_DATA_SIZE_32BIT,
} CRC_DataSize;

typedef void (*CRC_CallbackFxn) (CRC_Handle handle, int_fast16_t status, void *result);

typedef struct {
    CRC_ReturnBehavior      returnBehavior;
    CRC_CallbackFxn         callbackFxn;
    uint32_t                timeout;
    void                    *custom;

    uint32_t          seed;
    CRC_Polynomial    polynomial;
    uint32_t          programmablePoly;
    uint32_t          programmablePolyOrder;

    CRC_DataSize      dataSize;
    CRC_ByteSwap      byteSwapInput;

    uint8_t           reverseInputBits;
    uint8_t           invertOutputBits;
    uint8_t           reverseOutputBits;
    uint32_t          finalXorValue;
} CRC_Params;

extern const CRC_Params CRC_defaultParams;

extern void CRC_init(void);

extern void CRC_Params_init(CRC_Params *params);

extern CRC_Handle CRC_open(uint_least8_t index, const CRC_Params *params);

extern int_fast16_t CRC_calculateFull(CRC_Handle handle, const void *source, size_t sourceBytes, void *result);

extern int_fast16_t CRC_addData(CRC_Handle handle, const void *source, size_t sourceBytes);

extern void CRC_finalize(CRC_Handle handle, void *result);

extern void CRC_reset(CRC_Handle handle);

extern void CRC_close(CRC_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_CRC__include */