skids/perl6sum/lib/Sum/CRC
perl6sum src
NAME
Sum::CRC
SYNOPSIS
DESCRIPTION
The C<Sum::CRC> module provides roles for generating types of C<Sum>
that calculate a cyclic redundancy checksum. Many subroles are provided
for convenient access to well-standardized CRC parameter sets.
The base C<Sum::CRC> role variant is a bitwise implementation which
focuses on versatility. Based on the parameters used, alternate optimized
implementations may be composed instead (when they are eventually
implemented.) In some cases, forcing the use of optimizations may
require providing additional parameters.
ROLES
(head2) role Sum::CRC [ :@header?, :@footer?, :$residual = 0,
:$iniv = Bool::False, :$finv = Bool::False,
:$columns = 8, :$poly, :$reflect = Bool::False ]
does Sum::Partial
The C<Sum::CRC> parametric role is used to create a type of C<Sum>
that calculates a particular kind of cyclic redundancy checksum
based on the provided parameters. The resulting C<Sum> expects
single bit addends and will simply check the truth value of each
provided addend, unless a C<Sum::Marshal> role is mixed in.
The C<$columns> parameter specifies the number of bits in the final
checksum, and thus also the number of bits in many of the other
parameters.
The C<$poly> parameter defines the generator polynomial. The
format should be an integer where each bit represents a coefficient,
least significant coefficient mapped to least significant bit, with the
most significant term's coefficient truncated. The most significant
term is deduced from C<$columns> and is assumed to have a coefficient
of 1. This is sometimes called the "MSB-first code" or "normal code"
for a generator polynomial.
When C<:reflect> is specified, the remainder is swabbed bitwise
to produce final results. To swab input addends, mix in
appropriate C<Sum::Marshal> role(s) such as a C<Sum::Marshal::Bits>.
When C<:finv> is specified, the final result is bitwise inverted.
When a non-boolean value is specified for C<$finv>, the remainder
and this value are combined in a bitwise XOR when a result is
finalized. This happens after C<:reflect> swabbing, if any.
When C<:iniv> is specified, the remainder is set to all 1s at the
start of the checksum. When a non-boolean value is specified for
C<$iniv>, the remainder is initialized to the provided value.
This value is not adjusted to accomodate any C<:reflect> swabbing.
Note that a non-boolean value passed in C<:iniv> is assigned directly
to the remainder, which is not a typed attribute, so the value type is
assigned along with the value. This is left this way to provide
optimization flexibility, but is a potential gotcha if one were to
provide a type narrower than C<$columns> bits or which does not support
the required bitwise operations. Likewise a non-boolean value
provided in C<:finv> is used directly. When in doubt, coerce such
values to Int.
When C<@header> is provided, the addends it contains are provided
to the sum immediately upon initialization, after the remainder
is initialized according to the value of C<$iniv>. When C<@footer>
is provided, the addends it contains are provided to the sum before
a final result is produced. As partial sums are supported, the
remainder is then restored such that more addends may be provided.
Both C<@header> and C<@footer> are subject to the same marshalling
as provided by any C<Sum::Marshal> roles for normal addends.
The C<$residual> parameter is used in the C<.check> method, described
below.
(head2) METHODS
(head3) method check(*@addends)
The check method is intended to be used when verifying data
that includes an embedded precaculated CRC, such that the
sum of the original data and the CRC should produce a constant.
This method simply calls C<.finalize> and, if that succeeds,
returns C<True> if the resulting value is the same as the value
provided to the role in the C<$residual> role parameter.
CONVENIENCE ROLES
The following additional roles may be used to quickly create
classes that implement published CRC standards. Note that
there are cases where different CRC parameters have been
mistakenly called by the same name. Also note that a given
set of CRC parameters may be known by many names. These
roles are named to be unambiguous, even when an alternative
name may be more famous.
No complete list of names for different parameter sets is
offered by C<Sum::CRC>. For that, please consult the references
below.
(head2) role Sum::CRC_3_ROHC
does Sum::CRC[ :reflect, :columns(3), :poly(0x3) ]
Implements a 3-bit CRC used in RFC 3095 header compression.
(head2) role Sum::CRC_4_ITU
does Sum::CRC[ :reflect, :columns(4), :poly(0x3) ]
Implements a 4-bit CRC used in ITU G.704
(head2) role Sum::CRC_5_EPC
does Sum::CRC[ :iniv(9), :columns(5), :poly(0x9) ]
Implements a 5-bit CRC used in RFID.
(head2) role Sum::CRC_5_ITU
does Sum::CRC[ :reflect, :columns(5), :poly(0x15) ]
Implements a 5-bit CRC used in ITU G.704
(head2) role Sum::CRC_5_USB
does Sum::CRC[ :iniv, :finv, :columns(5), :poly(0x5),
:residual(0x13) ]
Implements a 5-bit CRC used in the USB protocol.
(head2) role Sum::CRC_6_DARC
does Sum::CRC[ :reflect, :columns(6), :poly(0x19) ]
Implements a 6-bit CRC used in the DARC radio protocol.
(head2) role Sum::CRC_6_ITU
does Sum::CRC[ :reflect, :columns(6), :poly(0x3) ]
Implements a 6-bit CRC used in ITU G.704
(head2) role Sum::CRC_7_JEDEC
does Sum::CRC[ :columns(7), :poly(0x9) ]
Implements a 7-bit CRC used in JEDEC multimedia cards.
(head2) role Sum::CRC_7_ROHC
does Sum::CRC[ :reflect, :iniv, :columns(7), :poly(0x4f) ]
Implements a 7-bit CRC used in RFC 3095 header compression.
(head2) role Sum::CRC_8_CCITT
does Sum::CRC[ :columns(8), :poly(0x7) ] { }
Implements a standardized 8-bit CRC used e.g. in SmBus.
(head2) role Sum::CRC_8_DARC
does Sum::CRC[ :reflect, :columns(8), :poly(0x39) ]
Implements an 8-bit CRC used in the DARC radio protocol.
(head2) role Sum::CRC_8_EBU
does Sum::CRC[ :reflect, :iniv, :columns(8), :poly(0x1d) ] { }
Implements an 8-bit CRC used in european digital audio
(head2) role Sum::CRC_8_I_CODE
does Sum::CRC[ :iniv(0xfd), :columns(8), :poly(0x1d) ] { }
Implements an 8-bit CRC used in I-CODE labels.
(head2) role Sum::CRC_8_ITU
does Sum::CRC[ :finv(0x55), :columns(8), :poly(0x7), :residual(0xf9) ]
Implements an 8-bit CRC used in ATM HEC codes.
(head2) role Sum::CRC_8_1_Wire
does Sum::CRC[ :reflect, :columns(8), :poly(0x31) ] { }
Implements an 8-bit CRC used in the 1-Wire bus standard.
(head2) role Sum::CRC_8_ROHC
does Sum::CRC[ :reflect, :iniv, :columns(8), :poly(0x7) ]
Implements an 8-bit CRC used in RFC 3095 header compression.
(head2) role Sum::CRC_8_WCDMA
does Sum::CRC[ :reflect, :columns(8), :poly(0x9b) ] { }
Implements an 8-bit CRC used in WDCMA wireless protocol.
(head2) role Sum::CRC_8_SAE_J1850
does Sum::CRC[ :iniv, :finv, :columns(8), :poly(0x1d),
:residual(0x3b) ] { }
Implements an 8-bit CRC used on the SAE J1850 automotive data bus.
(head2) role Sum::CRC_8_AUTOSAR
does Sum::CRC[ :iniv, :finv, :columns(8), :poly(0x2f),
:residual(0xbd) ]
Implements an 8-bit CRC used in automotive applications.
(head2) role Sum::CRC_10_AAL
does Sum::CRC[ :columns(10), :poly(0x233) ]
Implements a 10-bit CRC used in ATM AAL 3/4.
(head2) role Sum::CRC_11_FlexRay
does Sum::CRC[ :iniv(0x1a), :columns(11), :poly(0x385) ]
Implements an 11-bit CRC used in FlexRay automotive systems.
(head2) role Sum::CRC_12_3GPP
does Sum::CRC[ :reflect, :columns(12), :poly(0x80f) ]
Implements a 12-bit CRC used in 3G mobile systems.
(head2) role Sum::CRC_12_DECT
does Sum::CRC[ :columns(12), :poly(0x80f) ]
Implements a 12-bit CRC used in Digital Enhanced Cordless
Telecommunications.
(head2) role Sum::CRC_14_DARC
does Sum::CRC[ :reflect, :columns(14), :poly(0x805) ]
Implements a 14-bit CRC used in Digital Radio Communications.
(head2) role Sum::CRC_15_CAN
does Sum::CRC[ :columns(15), :poly(0x4599) ]
Implements a 15-bit CRC used in the Controller Area Network protocol.
(head2) role Sum::CRC_15_MPT1327
does Sum::CRC[ :finv(1), :columns(15), :poly(0x6815), :residual(0x6814)]
Implements a 15-bit CRC used in MPT1327 mobile communications.
(head2) role Sum::CRC_16_ANSI
does Sum::CRC[ :columns(16), :poly(0x8005) ]
Implements the ANSI 16-Bit CRC polynomial without any inversion or
reflection. Note this will be subject to problems with leading and
trailing zeros.
(head2) role Sum::CRC_16_LHA
does Sum::CRC[ :reflect, :columns(16), :poly(0x8005) ]
Implements a 16-Bit CRC using the ANSI 16-bit polynomial with
reflection of the result, as used by the lha data compression
utility. Note this will be subject to problems with leading
and trailing zeros.
(head2) role Sum::CRC_16_USB
does Sum::CRC[ :reflect, :iniv, :finv, :columns(16), :poly(0x8005),
:residual(0x4ffe) ]
Implements a 16-bit CRC used in the USB protocol. The result
is in host order, reflected from what appears on the wire.
(head2) role Sum::CRC_16_USB_WIRE
does Sum::CRC[ :iniv, :finv, :columns(16), :poly(0x8005),
:residual(0x7ff2) ]
Implements a 16-bit CRC used in the USB protocol. The result
is as it appears on the wire, unreflected.
(head2) role Sum::CRC_16_1_Wire
does Sum::CRC[ :finv, :reflect, :columns(16), :poly(0x8005),
:residual(0x8d1d) ]
Implements an 16-bit CRC used on the 1-Wire bus standard.
(head2) role Sum::CRC_16_Modbus
does Sum::CRC[ :iniv, :reflect, :columns(16), :poly(0x8005) ]
Implements a 16-bit CRC used in the Modbus protocol.
(head2) role Sum::CRC_16_DDS_110
does Sum::CRC[ :iniv(0x800d), :columns(16), :poly(0x8005) ]
Implements a 16-bit CRC used in the ELV DDS-110 function generator.
(head2) role Sum::CRC_16_X25
does Sum::CRC[ :reflect, :iniv, :finv, :columns(16), :poly(0x1021),
:residual(0xf47) ]
Implements a 16-bit CRC used in X.25 and other ITU-T standards.
This is the CCITT polynomial with the usual customary inversions
that protect against leading and trailing zeros, with bit order
reflected for use on LSB-first serial lines.
(head2) role Sum::CRC_16_EPC
does Sum::CRC[ :iniv, :finv, :columns(16), :poly(0x1021),
:residual(0xe2f0) ]
Implements a 16-bit CRC used in RFID tags. It is a modification
of C<Sum::CRC_8_X25> which does not require bit reflection.
(head2) role Sum::CRC_16_CCITT_TRUE
does Sum::CRC[ :reflect, :columns(16), :poly(0x1021) ]
Implements a commonly used 16-Bit CRC. This is version of
CRC which it is technically correct to call "CRC-16-CCITT",
though many call other CRCs this, referring only to the polynomial
in use. It does not contain inversions, and so does not protect
against leading and trailing zeros. It is bit reflected for
use on LSB-first transmission medium.
(head2) role Sum::CRC_16_XModem
does Sum::CRC[ :columns(16), :poly(0x1021) ]
Implements a 16-bit CRC as used in the XModem protocol. Note this
contains no inversions and as such does not protect against leading
or trailing zeros. It is a modification of CRC-16-CCITT-TRUE which
changes only the bit order.
(head2) role Sum::CRC_16_MCRF
does Sum::CRC[ :reflect, :iniv, :columns(16), :poly(0x1021) ]
Implements a 16-bit CRC used by some RFID chipsets. Note that
this algorithm does not protect against trailing zeros.
(head2) role Sum::CRC_16_CCITT_FALSE
does Sum::CRC[ :iniv, :columns(16), :poly(0x1021) ]
Calculates a 16-bit checksum which is in use e.g. in floppy
disks, but commonly mistaken for C<Sum::CRC_16_CCITT>, which
is slightly different. It does not protect against trailing
zeros.
(head2) role Sum::CRC_16_DNP
does Sum::CRC[ :finv, :reflect, :columns(16), :poly(0x3d65),
:residual(0x993a) ]
Implements a 16-bit CRC used in automation systems using
Distributed Network Protocol.
(head2) role Sum::CRC_16_EN_13757
does Sum::CRC[ :finv, :columns(16), :poly(0x3d65),
:residual(0x5c99) ]
Implements a 16-bit CRC used in utilities metering.
(head2) role Sum::CRC_16_T10_DIF
does Sum::CRC[ :columns(16), :poly(0x8bb7) ]
Implements a 16-bit CRC used in SCSI.
(head2) role Sum::CRC_16_Teledisk
does Sum::CRC[ :columns(16), :poly(0xa097) ]
Implements a 16-bit CRC used by Teledisk, DECNET, and other arcana.
(head2) role Sum::CRC_24_PGP
does Sum::CRC[ :iniv(0xb704ce), :columns(24), :poly(0x864cfb) ]
Implements the CRC defined in PGP RFC 4880.
(head2) role Sum::CRC_32
does Sum::CRC[ :iniv, :finv, :reflect, :columns(32), :poly(0x4c11db7),
:residual(0x2144df1c) ]
Implements one of the most prevalent 32-bit CRC sums, used in many
Internet standards.
(head2) role Sum::CRC_32_IEEE does Sum::CRC_32 { }
This is just a more specific name for C<Sum::CRC_32>.
(head2) role Sum::CRC_32C
does Sum::CRC[ :reflect, :iniv, :finv, :columns(32), :poly(0x1edc6f41),
:residual(0x48674bc7) ]
Implements a 32 bit CRC as used in iSCSI.
(head2) role Sum::CRC_32D
does Sum::CRC[ :reflect, :iniv, :finv, :columns(32), :poly(0xa833982b),
:residual(0xbad8faae) ]
Implements a 32 bit CRC used in Base91 ASCII armor.
(head2) role Sum::CRC_32_BZ2
does Sum::CRC[ :iniv, :finv, :columns(32), :poly(0x04c11db7),
:residual(0x38fb2284) ]
Implements a 32 bit CRC used e.g. in BZIP2, ATM-AAL5, and DECT.
(head2) role Sum::CRC_32_MPEG2
does Sum::CRC[ :iniv, :columns(32), :poly(0x04c11db7) ]
Implements a 32 bit CRC used in MPEG-2 streams. Note that this
CRC does not use a final inversion and is thus vulnerable to the
insertion of trailing bits.
(head2) role Sum::CRC_32Q
does Sum::CRC[ :columns(32), :poly(0x814141ab) ]
Implements the CRC-32Q sum as used in some aviation systems.
Note this CRC does not include inversions and as such is vulnerable
to the addition of leading and trailing zeros.
(head2) role Sum::CRC_32_XFER
does Sum::CRC[ :columns(32), :poly(0xaf) ]
Implements a CRC used by the XFER serial transfer protocol.
Note this CRC does not include inversions and as such is vulnerable
to the addition of leading and trailing zeros.
(head2) role Sum::CRC_40_GSM
does Sum::CRC[ :columns(40), :poly(0x4820009) ] { }
Implements the GSM FIRE code CRC. Note this CRC does not include
inversions and as such is vulnerable to the addition of leading
and trailing zeros.
(head2) role Sum::CRC_64_ISO
does Sum::CRC[ :reflect, :columns(64), :poly(0x1b) ]
Implements the ISO 3309 64 bit CRC. Note this CRC does not include
inversions and as such is vulnerable to the addition of leading and
trailing zeros.
(head2) role Sum::CRC_64_DLT
does Sum::CRC[ :columns(64), :poly(0x42f0e1eba9ea3693) ]
Implements a CRC using the ECMA-182 polynomial as used in DLT-1 tapes.
Note this CRC does not include inversions and as such is vulnerable
to the addition of leading and trailing zeros.
(head2) role Sum::CRC_64_XZ
does Sum::CRC[ :iniv, :finv, :reflect, :columns(64),
:poly(0x42f0e1eba9ea3693),
:residual(0xb66a73654282cac0) ]
Implements a CRC using the ECMA/DLT polynomial as used in the C<.xz>
file format. This adds the customary codeword inversions to provide
protection against leading and trailing zeros, and also reflects the
input values and codewords.
(head2) role Sum::CRC_64_Jones
does Sum::CRC[ :reflect, :iniv, :columns(64), :poly(0xad93d23594c935a9) ]
Implements a CRC as proposed in
http://www.cs.ucl.ac.uk/staff/d.jones/crcnote.pdf. Note this
implementation does not include C<:finv> and as such, does not
use a residual and is thus vulnerable to the addition of trailing zeros.
(head2) role Sum::CRC_82_DARC
does Sum::CRC[ :reflect, :iniv, :columns(64), :poly(0xad93d23594c935a9) ]
Implements a CRC used in Digital Radio Communications (DARC).
AUTHOR
Written by Brian S. Julin
COPYRIGHT
Copyright (c) 2012 Brian S. Julin. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the terms
of the Perl Artistic License 2.0.
REFERENCES
http://reveng.sourceforge.net/crc-catalogue
http://crcmod.sourceforge.net/crcmod.predefined.html Python crc modules
http://www.ece.cmu.edu/~koopman/roses/dsn04/koopman04_crc_poly_embedded.pdf
"SAE Standard J1850 Class B Data Communication Network Interface" 2/15/94
"Specification of CRC Routines" V3.3.0 R3.2 Rev 2 AUTOSAR document ID 016
SEE ALSO
C<Sum::(pm3)>
