1crc32c 2====== 3 4.. image:: https://github.com/ICRAR/crc32c/workflows/Build%20and%20release%20to%20PyPI/badge.svg?branch=master 5 6.. image:: https://badge.fury.io/py/crc32c.svg 7 :target: https://badge.fury.io/py/crc32c 8 9This package implements the crc32c checksum algorithm. 10It automatically chooses between a hardware-based implementation 11(using the CRC32C SSE 4.2 instruction of Intel CPUs, 12and the crc32* instructions on ARMv8 CPUs), 13or a software-based one when no hardware support can be found. 14 15Because ``crc32c`` is in PyPI, you can install it with:: 16 17 pip install crc32c 18 19Supported platforms are Linux and OSX using the gcc and clang compilers, 20and Windows using the Visual Studio compiler. Other compilers in 21Windows (MinGW for instance) might work. 22Binary wheels are also provided in PyPI for major platforms/architectures. 23 24 25Usage 26----- 27 28The only method exposed by this module is ``crc32c(data, [crc])``. 29It computes the CRC32C checksum of ``data`` 30starting with an initial ``crc`` checksum, 31similarly to how the built-in ``binascii.crc32`` works. 32It can thus be used like this: 33 34.. code-block:: python 35 36 print(crc32c.crc32c(b'hello world')) 37 # 3381945770 38 crc = crc32c.crc32c(b'hello') 39 print(crc32c.crc32c(b' world', crc)) 40 # 3381945770 41 42In older versions, 43the function exposed by this module was called ``crc32``. 44That name is still present but deprecated, 45and will be removed in new versions of the library. 46 47Additionally one can consult 48the ``hardware_based`` module-level value 49to check if the algorithm currently in use 50is software- or hardware-based. 51 52 53Implementation details 54---------------------- 55 56By default, 57if your CPU doesn't have CRC32C hardware support, 58the package will fallback to use a software implementation 59of the crc32c checksum algorithm. 60This behavior can be changed by setting 61the ``CRC32C_SW_MODE`` environment variable 62to one of the following values: 63 64* ``auto``: same as if unset, will eventually be discontinued. 65* ``force``: use software implementation regardless of hardware support. 66* ``none``: fail to import the module with an ``ImportError`` 67 if no hardware support is found (old 1.x default behavior). 68 69The software algorithm is based 70on Intel's `slice-by-8 package <https://sourceforge.net/projects/slicing-by-8/>`_, 71with some adaptations done 72by `Evan Jones <https://www.evanjones.ca/crc32c.html>`_ 73and packaging provided by `Ferry Toth <https://github.com/htot/crc32c>`_. 74Further adaptations were required 75to make the code more portable 76and fit for inclusion within this python package. 77 78The Intel SSE 4.2 algorithm 79is based on `Mark Adler's code <http://stackoverflow.com/questions/17645167/implementing-sse-4-2s-crc32c-in-software/17646775>`_, 80with some modifications required 81to make the code more portable 82and fit for inclusion within this python package. 83 84The ARMv8 hardware implementation 85is based on Google's `crc32c <https://github.com/google/crc32c>`_ 86C++ library. 87 88Copyright 89--------- 90 91This package is copyrighted:: 92 93 ICRAR - International Centre for Radio Astronomy Research 94 (c) UWA - The University of Western Australia, 2017 95 Copyright by UWA (in the framework of the ICRAR) 96 97The original slice-by-8 software algorithm 98is copyrighted by:: 99 100 Copyright (c) 2004-2006 Intel Corporation - All Rights Reserved 101 102Further adaptations to the slice-by-8 algorithm 103previous to the inclusion in this package 104are copyrighted by:: 105 106 Copyright 2008,2009,2010 Massachusetts Institute of Technology. 107 108The original Intel SSE 4.2 crc32c algorithm 109is copyrighted by:: 110 111 Copyright (C) 2013 Mark Adler 112 113The crc32c ARMv8 hardware code 114is copyrighted by:: 115 116 Copyright 2017 The CRC32C Authors 117 118A copy of the `AUTHORS <AUTHORS.google-crc32c>`_ file 119from Google's crc32c project 120as it was at the time of copying the code 121is included in this repository. 122 123License 124------- 125 126This package is licensed under `the LGPL-2.1 license <LICENSE>`_. 127 128The original slice-by-8 software algorithm 129is licensed under `the 2-clause BSD licence 130<https://opensource.org/licenses/bsd-license.html>`_. 131 132Further modifications to the slice-by-8 software algorithm 133are licensed under `a 3-clause BSD licence <LICENSE.slice-by-8>`_ 134 135The original Intel SSE 4.2 crc32c algorithm's code 136is licensed under a custom license 137embedded in the ``crc32c_adler.c`` file. 138 139The original crc32c ARMv8 hardware code 140is licensed under `a 3-clause BSD license <LICENSE.google-crc32c>`_. 141