1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Introduction — crcmod v1.7 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '1.7',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="crcmod v1.7 documentation" href="index.html" />
<link rel="next" title="crcmod – CRC calculation" href="crcmod.html" />
<link rel="prev" title="crcmod documentation" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="crcmod.html" title="crcmod – CRC calculation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="crcmod documentation"
accesskey="P">previous</a> |</li>
<li><a href="index.html">crcmod v1.7 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<p>The software in this package is a Python module for generating objects that
compute the Cyclic Redundancy Check (CRC). It includes a (optional) C
extension for fast calculation, as well as a pure Python implementation.</p>
<p>There is no attempt in this package to explain how the CRC works. There are a
number of resources on the web that give a good explanation of the algorithms.
Just do a Google search for “crc calculation” and browse till you find what you
need. Another resource can be found in chapter 20 of the book “Numerical
Recipes in C” by Press et. al.</p>
<p>This package allows the use of any 8, 16, 24, 32, or 64 bit CRC. You can
generate a Python function for the selected polynomial or an instance of the
<a title="crcmod.Crc" class="reference external" href="crcmod.html#crcmod.Crc"><tt class="xref docutils literal"><span class="pre">crcmod.Crc</span></tt></a> class which provides the same interface as the
<a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/hashlib.html#module-hashlib"><tt class="xref docutils literal"><span class="pre">hashlib</span></tt></a>, <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/md5.html#module-md5"><tt class="xref docutils literal"><span class="pre">md5</span></tt></a> and <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/sha.html#module-sha"><tt class="xref docutils literal"><span class="pre">sha</span></tt></a> modules from the Python standard
library. A <a title="crcmod.Crc" class="reference external" href="crcmod.html#crcmod.Crc"><tt class="xref docutils literal"><span class="pre">crcmod.Crc</span></tt></a> class instance can also generate C/C++ source
code that can be used in another application.</p>
<div class="section" id="guidelines">
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline">¶</a></h2>
<p>Documentation is available here as well as from the doc strings.</p>
<p>It is up to you to decide what polynomials to use in your application. Some
common CRC algorithms are predefined in <a title="CRC calculation using predefined algorithms" class="reference external" href="crcmod.predefined.html#module-crcmod.predefined"><tt class="xref docutils literal"><span class="pre">crcmod.predefined</span></tt></a>. If someone
has not specified the polynomials to use, you will need to do some research to
find one suitable for your application. Examples are available in the unit
test script <tt class="docutils literal"><span class="pre">test.py</span></tt>.</p>
<p>If you need to generate code for another language, I suggest you subclass the
<a title="crcmod.Crc" class="reference external" href="crcmod.html#crcmod.Crc"><tt class="xref docutils literal"><span class="pre">crcmod.Crc</span></tt></a> class and replace the method
<a title="crcmod.Crc.generateCode" class="reference external" href="crcmod.html#crcmod.Crc.generateCode"><tt class="xref docutils literal"><span class="pre">crcmod.Crc.generateCode()</span></tt></a>. Use <a title="crcmod.Crc.generateCode" class="reference external" href="crcmod.html#crcmod.Crc.generateCode"><tt class="xref docutils literal"><span class="pre">crcmod.Crc.generateCode()</span></tt></a> as a
model for the new version.</p>
</div>
<div class="section" id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
<div class="section" id="python-version">
<h3>Python Version<a class="headerlink" href="#python-version" title="Permalink to this headline">¶</a></h3>
<p>The package has separate code to support the 2.x and 3.x Python series.</p>
<p>For the 2.x versions of Python, these versions have been tested:</p>
<ul class="simple">
<li>2.4</li>
<li>2.5</li>
<li>2.6</li>
<li>2.7</li>
</ul>
<p>It may still work on earlier versions of Python 2.x, but these have not been
recently tested.</p>
<p>For the 3.x versions of Python, these versions have been tested:</p>
<ul class="simple">
<li>3.1</li>
</ul>
</div>
<div class="section" id="building-c-extension">
<h3>Building C extension<a class="headerlink" href="#building-c-extension" title="Permalink to this headline">¶</a></h3>
<p>To build the C extension, the appropriate compiler tools for your platform must
be installed. Refer to the Python documentation for building C extensions for
details.</p>
</div>
</div>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>The <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a> package is installed using <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/distutils.html#module-distutils"><tt class="xref docutils literal"><span class="pre">distutils</span></tt></a>.
Run the following command:</p>
<div class="highlight-python"><pre>python setup.py install</pre>
</div>
<p>If the extension module builds, it will be installed. Otherwise, the
installation will include the pure Python version. This will run significantly
slower than the extension module but will allow the package to be used.</p>
<p>For Windows users who want to use the mingw32 compiler, run this command:</p>
<div class="highlight-python"><pre>python setup.py build --compiler=mingw32 install</pre>
</div>
<p>For Python 3.x, the install process is the same but you need to use the 3.x
interpreter.</p>
</div>
<div class="section" id="unit-testing">
<h2>Unit Testing<a class="headerlink" href="#unit-testing" title="Permalink to this headline">¶</a></h2>
<p>The <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a> package has a module <tt class="xref docutils literal"><span class="pre">crcmod.test</span></tt>, which contains
unit tests for both <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a> and <a title="CRC calculation using predefined algorithms" class="reference external" href="crcmod.predefined.html#module-crcmod.predefined"><tt class="xref docutils literal"><span class="pre">crcmod.predefined</span></tt></a>.</p>
<p>When you first install <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a>, you should run the unit tests to make
sure everything is installed properly. The test script performs a number of
tests including a comparison to the direct method which uses a class
implementing polynomials over the integers mod 2.</p>
<p>To run the unit tests on Python >=2.5:</p>
<div class="highlight-python"><pre>python -m crcmod.test</pre>
</div>
<p>Alternatively, in the <tt class="docutils literal"><span class="pre">test</span></tt> directory run:</p>
<div class="highlight-python"><pre>python test_crcmod.py</pre>
</div>
</div>
<div class="section" id="code-generation">
<h2>Code Generation<a class="headerlink" href="#code-generation" title="Permalink to this headline">¶</a></h2>
<p>The <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a> package is capable of generating C functions that can be
compiled with a C or C++ compiler. In the <tt class="docutils literal"><span class="pre">test</span></tt> directory, there is an
<tt class="docutils literal"><span class="pre">examples.py</span></tt> script that demonstrates how to use the code generator.
The result of this is written out to the file <tt class="docutils literal"><span class="pre">examples.c</span></tt>. The
generated code was checked to make sure it compiles with the GCC compiler.</p>
</div>
<div class="section" id="license">
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
<p>The <a title="CRC calculation" class="reference external" href="crcmod.html#module-crcmod"><tt class="xref docutils literal"><span class="pre">crcmod</span></tt></a> package is released under the MIT license. See the
<tt class="docutils literal"><span class="pre">LICENSE</span></tt> file for details.</p>
</div>
<div class="section" id="references">
<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/binascii.html#binascii.crc32"><tt class="xref docutils literal"><span class="pre">binascii.crc32()</span></tt></a> function from the <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/binascii.html#module-binascii"><tt class="xref docutils literal"><span class="pre">binascii</span></tt></a> module</dt>
<dd>CRC-32 implementation</dd>
<dt><a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/zlib.html#zlib.crc32"><tt class="xref docutils literal"><span class="pre">zlib.crc32()</span></tt></a> function from the <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/zlib.html#module-zlib"><tt class="xref docutils literal"><span class="pre">zlib</span></tt></a> module</dt>
<dd>CRC-32 implementation</dd>
<dt>Module <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/hashlib.html#module-hashlib"><tt class="xref docutils literal"><span class="pre">hashlib</span></tt></a></dt>
<dd>Secure hash and message digest algorithms.</dd>
<dt>Module <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/md5.html#module-md5"><tt class="xref docutils literal"><span class="pre">md5</span></tt></a></dt>
<dd>RSA’s MD5 message digest algorithm.</dd>
<dt>Module <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/sha.html#module-sha"><tt class="xref docutils literal"><span class="pre">sha</span></tt></a></dt>
<dd>NIST’s secure hash algorithm, SHA.</dd>
<dt>Module <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/hmac.html#module-hmac"><tt class="xref docutils literal"><span class="pre">hmac</span></tt></a></dt>
<dd>Keyed-hashing for message authentication.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Introduction</a><ul>
<li><a class="reference external" href="#guidelines">Guidelines</a></li>
<li><a class="reference external" href="#dependencies">Dependencies</a><ul>
<li><a class="reference external" href="#python-version">Python Version</a></li>
<li><a class="reference external" href="#building-c-extension">Building C extension</a></li>
</ul>
</li>
<li><a class="reference external" href="#installation">Installation</a></li>
<li><a class="reference external" href="#unit-testing">Unit Testing</a></li>
<li><a class="reference external" href="#code-generation">Code Generation</a></li>
<li><a class="reference external" href="#license">License</a></li>
<li><a class="reference external" href="#references">References</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">crcmod documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="crcmod.html"
title="next chapter"><tt class="docutils literal docutils literal docutils literal"><span class="pre">crcmod</span></tt> – CRC calculation</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/intro.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="crcmod.html" title="crcmod – CRC calculation"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="crcmod documentation"
>previous</a> |</li>
<li><a href="index.html">crcmod v1.7 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, Raymond L Buvel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
</div>
</body>
</html>
|
