generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/doc/html/crc/crc_basic.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

448 lines
23 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Theoretical CRC Computer</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../crc.html" title="Chapter 12. Boost.CRC 1.5">
<link rel="prev" href="introduction.html" title="Introduction">
<link rel="next" href="crc_optimal.html" title="Optimized CRC Computer">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="introduction.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../crc.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="crc_optimal.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="crc.crc_basic"></a><a class="link" href="crc_basic.html" title="Theoretical CRC Computer">Theoretical CRC Computer</a>
</h2></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstddef</span><span class="special">&gt;</span> <span class="comment">// for std::size_t</span>
<span class="keyword">namespace</span> <span class="identifier">boost</span>
<span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">Bits</span> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">crc_basic</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
The <span class="bold"><strong><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_basic</span></code></strong></span>
class template acts as an unaugmented-CRC processor that can accept input at
the bit-level. It only takes one Rocksoft™ Model CRC Algorithm parameter
as a template parameter, the <span class="emphasis"><em>WIDTH</em></span>, which determines the
built-in unsigned integer type used for division registers. The other Rocksoft™
Model CRC Algorithm parameters can be passed on through the constructor. (Most
of the parameters have defaults.)
</p>
<p>
The integer type used for registers is published as <code class="computeroutput"><span class="identifier">value_type</span></code>,
while the Rocksoft™ Model CRC Algorithm attributes can be discovered
as:
</p>
<div class="table">
<a name="crc.crc_basic.crc_basic_rmca"></a><p class="title"><b>Table 12.1. RMCA Parameters in boost::crc_basic</b></p>
<div class="table-contents"><table class="table" summary="RMCA Parameters in boost::crc_basic">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Parameter
</p>
</th>
<th>
<p>
Member Name
</p>
</th>
<th>
<p>
Kind
</p>
</th>
<th>
<p>
Expression Type
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<span class="emphasis"><em>WIDTH</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">bit_count</span></code>
</p>
</td>
<td>
<p>
class-static immutable data member
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>POLY</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">get_truncated_polynominal</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">const</span></code> member function
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">value_type</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>INIT</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">get_initial_remainder</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">const</span></code> member function
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">value_type</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>REFIN</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">get_reflect_input</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">const</span></code> member function
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>REFOUT</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">get_reflect_remainder</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">const</span></code> member function
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">bool</span></code>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="emphasis"><em>XOROUT</em></span>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">get_final_xor_value</span></code>
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="keyword">const</span></code> member function
</p>
</td>
<td>
<p>
<code class="computeroutput"><span class="identifier">value_type</span></code>
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
Since most of the parameters are specified at run-time, you can reuse a single
computer object for separate runs with differing parameters. The type uses
the automatically-defined copy/move/assign and destruction routines.
</p>
<p>
Here's an example of reuse:
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">unsigned</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">&gt;</span> <span class="identifier">crc_16_and_xmodem</span><span class="special">(</span> <span class="keyword">void</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">b</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">l</span> <span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">unsigned</span><span class="special">,</span> <span class="keyword">unsigned</span><span class="special">&gt;</span> <span class="identifier">result</span><span class="special">;</span>
<a class="co" name="crc.crc_basic.c0" href="crc_basic.html#crc.crc_basic.c1"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_basic</span><span class="special">&lt;</span><span class="number">16</span><span class="special">&gt;</span> <span class="identifier">crc1</span><span class="special">(</span> <span class="number">0x8005u</span><span class="special">,</span> <span class="number">0u</span><span class="special">,</span> <span class="number">0u</span><span class="special">,</span> <span class="keyword">true</span><span class="special">,</span> <span class="keyword">true</span> <span class="special">);</span>
<span class="identifier">crc1</span><span class="special">.</span><span class="identifier">process_bytes</span><span class="special">(</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">l</span> <span class="special">);</span>
<span class="identifier">result</span><span class="special">.</span><span class="identifier">first</span> <span class="special">=</span> <span class="identifier">crc1</span><span class="special">.</span><span class="identifier">checksum</span><span class="special">();</span>
<a class="co" name="crc.crc_basic.c2" href="crc_basic.html#crc.crc_basic.c3"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">crc1</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_basic</span><span class="special">&lt;</span><span class="number">16</span><span class="special">&gt;(</span> <span class="number">0x8408u</span><span class="special">,</span> <span class="identifier">crc1</span><span class="special">.</span><span class="identifier">get_initial_remainder</span><span class="special">(),</span>
<span class="identifier">crc1</span><span class="special">.</span><span class="identifier">get_final_xor_value</span><span class="special">(),</span> <span class="identifier">crc1</span><span class="special">.</span><span class="identifier">get_reflect_input</span><span class="special">(),</span>
<span class="identifier">crc1</span><span class="special">.</span><span class="identifier">get_reflect_remainder</span><span class="special">()</span> <span class="special">);</span>
<span class="identifier">crc1</span><span class="special">.</span><span class="identifier">process_bytes</span><span class="special">(</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">l</span> <span class="special">);</span>
<span class="identifier">result</span><span class="special">.</span><span class="identifier">second</span> <span class="special">=</span> <span class="identifier">crc1</span><span class="special">.</span><span class="identifier">checksum</span><span class="special">();</span>
<span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
For now, most Rocksoft™ Model CRC Algorithm parameters can only be changed
through assignment to the entire object.
</p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="crc.crc_basic.c1"></a><a href="#crc.crc_basic.c0"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The parameters are based on <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_16_type</span></code>.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="crc.crc_basic.c3"></a><a href="#crc.crc_basic.c2"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
Change the parameters to match <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_xmodem_type</span></code>.
</p></td>
</tr>
</table></div>
<p>
This example necessarily demonstrates input and output. There is one output
member function, <code class="computeroutput"><span class="identifier">checksum</span></code> that
returns the remainder from the CRC steps plus any post-processing reflection
and/or XOR-masking. There are several options to submit input data for processing:
</p>
<div class="table">
<a name="crc.crc_basic.crc_basic_input"></a><p class="title"><b>Table 12.2. Member Functions for Input in boost::crc_basic</b></p>
<div class="table-contents"><table class="table" summary="Member Functions for Input in boost::crc_basic">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Member Function
</p>
</th>
<th>
<p>
Input Type/Style
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">process_bit</span></code>
</p>
</td>
<td>
<p>
A single bit.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">process_bits</span></code>
</p>
</td>
<td>
<p>
A specified number of bits within the given byte. Reading starts
from the highest-order desired bit.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">process_byte</span></code>
</p>
</td>
<td>
<p>
An entire byte. The bits within the byte are read in an order consistent
with <code class="computeroutput"><span class="identifier">get_reflect_input</span></code>.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">process_block</span></code>
</p>
</td>
<td>
<p>
All bytes in the range. The range is defined by a pointer to the
first byte and another pointer to one (byte) past-the-end.
</p>
</td>
</tr>
<tr>
<td>
<p>
<code class="computeroutput"><span class="identifier">process_bytes</span></code>
</p>
</td>
<td>
<p>
All bytes in the range. The range is defined by a pointer to the
first byte and a count of number of bytes to read.
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
The input functions currently do not return anything.
</p>
<p>
Persistent objects mean that the data doesn't have to be in one block:
</p>
<p>
</p>
<pre class="programlisting"><span class="keyword">unsigned</span> <span class="identifier">combined_crc_16</span><span class="special">(</span> <span class="keyword">unsigned</span> <span class="identifier">block_count</span><span class="special">,</span> <span class="special">...</span> <span class="special">)</span>
<span class="special">{</span>
<a class="co" name="crc.crc_basic.c4" href="crc_basic.html#crc.crc_basic.c5"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
<a class="co" name="crc.crc_basic.c6" href="crc_basic.html#crc.crc_basic.c7"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_basic</span><span class="special">&lt;</span><span class="number">16</span><span class="special">&gt;</span> <span class="identifier">crc1</span><span class="special">(</span> <span class="number">0x8005u</span><span class="special">,</span> <span class="number">0u</span><span class="special">,</span> <span class="number">0u</span><span class="special">,</span> <span class="keyword">true</span><span class="special">,</span> <span class="keyword">true</span> <span class="special">);</span>
<span class="identifier">va_list</span> <span class="identifier">ap</span><span class="special">;</span>
<span class="identifier">va_start</span><span class="special">(</span> <span class="identifier">ap</span><span class="special">,</span> <span class="identifier">block_count</span> <span class="special">);</span>
<span class="keyword">while</span> <span class="special">(</span> <span class="identifier">block_count</span><span class="special">--</span> <span class="special">)</span>
<span class="special">{</span>
<span class="keyword">void</span> <span class="keyword">const</span> <span class="special">*</span> <span class="keyword">const</span> <span class="identifier">bs</span> <span class="special">=</span> <span class="identifier">va_arg</span><span class="special">(</span> <span class="identifier">ap</span><span class="special">,</span> <span class="keyword">void</span> <span class="keyword">const</span> <span class="special">*</span> <span class="special">);</span>
<span class="identifier">size_t</span> <span class="keyword">const</span> <span class="identifier">bl</span> <span class="special">=</span> <span class="identifier">va_arg</span><span class="special">(</span> <span class="identifier">ap</span><span class="special">,</span> <span class="identifier">size_t</span> <span class="special">);</span>
<a class="co" name="crc.crc_basic.c8" href="crc_basic.html#crc.crc_basic.c9"><img src="../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="identifier">crc1</span><span class="special">.</span><span class="identifier">process_bytes</span><span class="special">(</span> <span class="identifier">bs</span><span class="special">,</span> <span class="identifier">bl</span> <span class="special">);</span>
<span class="special">}</span>
<span class="identifier">va_end</span><span class="special">(</span> <span class="identifier">ap</span> <span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">crc1</span><span class="special">.</span><span class="identifier">checksum</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
No CRC operation throws, so there is no need for extra protection between the
varargs macro calls.
</p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="crc.crc_basic.c5"></a><a href="#crc.crc_basic.c4"><img src="../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
C-style variable-argument routines are or may be macros.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="crc.crc_basic.c7"></a><a href="#crc.crc_basic.c6"><img src="../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The parameters are based on <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">crc_16_type</span></code>.
</p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="crc.crc_basic.c9"></a><a href="#crc.crc_basic.c8"><img src="../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
The <code class="computeroutput"><span class="identifier">va_arg</span></code> calls were within
the <code class="computeroutput"><span class="identifier">process_bytes</span></code> call,
but I remembered that calling order is not guaranteed among function arguments,
so I need explicit object declarations to enforce the extraction order.
</p></td>
</tr>
</table></div>
<p>
The input-influenced state of a computer object may be read with the <code class="computeroutput"><span class="identifier">get_interim_remainder</span></code> member function. An
object may be loaded with the same kind of state with the one-argument version
of the <code class="computeroutput"><span class="identifier">reset</span></code> member function.
The state is the remainder from the CRC operations performed on all the already-entered
input, without any output post-processing.
</p>
<p>
The two functions can be used together to save the state to a persistent medium
and restore it later. Note that the Rocksoft™ Model CRC Algorithm parameters
have to saved/restored via other means, if they're not fixed within a program.
</p>
<p>
Calling <code class="computeroutput"><span class="identifier">reset</span></code> with no arguments
sets the interim remainder to what <span class="emphasis"><em>INIT</em></span> was set at object
construction. This lets one computer object be used for independent runs with
separate data messages using the same CRC standard.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001, 2003, 2012 Daryle Walker<p>
Distributed under the Boost Software License, Version 1.0. (See the accompanying
file LICENSE_1_0.txt or a copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="introduction.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../crc.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="crc_optimal.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink