Blame - third_party/pycrc/doc/pycrc.xml - RealtimeRoboticsGroup/test

<para>calculate the checksum of a string (default: <quote><replaceable>123456789</replaceable></quote>). If the string contains non-ASCII characters then it will be UTF-8 decoded.</para>

166

</listitem>

167

</varlistentry>

168

169

<term>

170

<option>--check-hexstring=</option><replaceable>STRING</replaceable>

171

</term>

172

173

<para>calculate the checksum of a hexadecimal number string.</para>

</listitem>

</varlistentry>

<term>

<option>--check-file=</option><replaceable>FILE</replaceable>

179

</term>

180

181

<para>calculate the checksum of a file. If the file contains non-ASCII characters then it will be UTF-8 decoded.</para>

</listitem>

</varlistentry>

<term>

<option>--generate=</option><replaceable>CODE</replaceable>

187

</term>

188

189

<para>generate C source code; choose the type from {<replaceable>h</replaceable>,

190

<replaceable>c</replaceable>, <replaceable>c-main</replaceable>, <replaceable>table</replaceable>}.</para>

</listitem>

</varlistentry>

<term>

</term>

<para>specify the C dialect of the generated code from {C89, ANSI, C99}.</para>

</listitem>

</varlistentry>

<term>

<option>--algorithm=</option><replaceable>ALGO</replaceable>

204

</term>

205

206

<para>choose an algorithm from {<replaceable>bit-by-bit</replaceable>, <replaceable>bbb</replaceable>,

207

<replaceable>bit-by-bit-fast</replaceable>, <replaceable>bbf</replaceable>,

208

<replaceable>table-driven</replaceable>, <replaceable>tbl</replaceable>,

</listitem>

</varlistentry>

<term>

<option>--model=</option><replaceable>MODEL</replaceable>

215

</term>

216

217

<para>choose a parameter set from

218

{<replaceable>crc-5</replaceable>,

219

<replaceable>crc-8</replaceable>,

220

<replaceable>dallas-1-wire</replaceable>,

221

<replaceable>crc-12-3gpp</replaceable>,

222

<replaceable>crc-15</replaceable>,

223

<replaceable>crc-16</replaceable>,

224

<replaceable>crc-16-usb</replaceable>,

225

<replaceable>crc-16-modbus</replaceable>,

226

<replaceable>crc-16-genibus</replaceable>,

227

<replaceable>crc-16-ccitt</replaceable>,

228

<replaceable>r-crc-16</replaceable>,

229

<replaceable>kermit</replaceable>,

230

<replaceable>x-25</replaceable>,

231

<replaceable>xmodem</replaceable>,

232

<replaceable>zmodem</replaceable>,

233

<replaceable>crc-24</replaceable>,

234

<replaceable>crc-32</replaceable>,

235

<replaceable>crc-32c</replaceable>,

236

<replaceable>crc-32-mpeg</replaceable>,

237

<replaceable>crc-32-bzip2</replaceable>,

238

<replaceable>posix</replaceable>,

239

<replaceable>jam</replaceable>,

240

<replaceable>xfer</replaceable>,

241

<replaceable>crc-64</replaceable>,

242

<replaceable>crc-64-jones</replaceable>,

</listitem>

</varlistentry>

<term>

<option>--width=</option><replaceable>NUM</replaceable>

</term>

</listitem>

</varlistentry>

<term>

</term>

</listitem>

</varlistentry>

<term>

<option>--reflect-in=</option><replaceable>BOOL</replaceable>

265

</term>

266

267

<para>reflect the octets in the input message.</para>

</listitem>

</varlistentry>

<term>

</term>

<para>use <replaceable>HEX</replaceable> as initial value.</para>

</listitem>

</varlistentry>

<term>

<option>--reflect-out=</option><replaceable>BOOL</replaceable>

281

</term>

282

283

<para>reflect the resulting checksum before applying the &xor_out; value.</para>

</listitem>

</varlistentry>

<term>

</term>

<para>xor the final CRC value with <replaceable>HEX</replaceable>.</para>

</listitem>

</varlistentry>

<term>

<option>--slice-by=</option><replaceable>NUM</replaceable>

297

</term>

298

299

<para>speed-up the &table-driven; calculation by operating on

300

<replaceable>NUM</replaceable> octets of data rather than a

301

single octet at a time.

302

<replaceable>NUM</replaceable> must be one of the values

303

{<replaceable>4</replaceable>, <replaceable>8</replaceable>,

</listitem>

</varlistentry>

<term>

<option>--table-idx-width=</option><replaceable>NUM</replaceable>

310

</term>

311

312

<para>use <replaceable>NUM</replaceable> bits to index the CRC table;

313

<replaceable>NUM</replaceable> must be one of the values

314

{<replaceable>1</replaceable>, <replaceable>2</replaceable>,

</listitem>

</varlistentry>

<term>

<option>--force-poly</option>

321

</term>

322

323

<para>override any errors about possibly unsuitable

324

polynoms. pycrc does not allow even polynoms or

325

polynoms that are wider than &width;. Use this option

326

to override the error, if you know what you are

doing.</para>

</listitem>

</varlistentry>

<term>

<option>--symbol-prefix=</option><replaceable>STRING</replaceable>

333

</term>

334

335

<para>when generating source code, use <replaceable>STRING</replaceable>

336

as prefix to the exported C symbols.</para>

</listitem>

</varlistentry>

<term>

<option>--crc-type=</option><replaceable>STRING</replaceable>

342

</term>

343

344

<para>when generating source code, use <replaceable>STRING</replaceable> as crc_t type.</para>

</listitem>

</varlistentry>

<term>

<option>--include-file=</option><replaceable>FILE</replaceable>

350

</term>

351

352

<para>when generating source code, include also <replaceable>FILE</replaceable> as header file.

353

This option can be specified multiple times.</para>

</listitem>

</varlistentry>

<term>

</term>

<term>

<option>--output=</option><replaceable>FILE</replaceable>

362

</term>

363

364

<para>write the generated code to <replaceable>FILE</replaceable> instead of <filename>stdout</filename>.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<title>The CRC Parametric Model</title>

372

<para>

373

The parametric model follows Ross N. Williams' convention described in

374

375

often called the Rocksoft Model.

376

Since most people are familiar with this kind of parameters, pycrc follows this convention, described as follows:

377

378

379

<glossterm><replaceable>&width;</replaceable></glossterm>

380

381

<para>

382

The number of significant bits in the CRC <replaceable>&poly;</replaceable>,

383

excluding the most significant 1.

384

This will also be the number of bits in the final CRC result.

385

In previous versions of pycrc only multiples of 8 could be used as

386

<replaceable>&width;</replaceable> for the <replaceable>&table-driven;</replaceable> algorithm.

387

As of version 0.7.5 any value is accepted for <replaceable>&width;</replaceable> for all algorithms.

</para>

</glossdef>

</glossentry>

<para>

The unreflected polynomial of the CRC algorithm.

396

</para>

397

<para>

398

The <replaceable>&poly;</replaceable> may be specified in its standard form,

399

i.e. with bit <replaceable>&width;</replaceable>+1 set to 1, but the most significant

400

bit may also be omitted.

401

For example, both numbers 0x18005 and 0x8005 are accepted for a 16-bit

402

<replaceable>&poly;</replaceable>.

403

</para>

404

<para>

405

Most polynomials used in real world applications are odd (the least significant

406

bit is 1), but there are some good even ones.

407

pycrc allows the use of even polynomials with the <option>--force-poly</option>

408

option.

409

Some even polynomials may yield incorrect checksums depending on the used algorithm.

410

Use at your own risk and if at all possible use a well-known <replaceable>MODEL</replaceable> above.

</para>

</glossdef>

</glossentry>

<glossterm><replaceable>&reflect_in;</replaceable></glossterm>

416

417

<para>

418

Reflect the octets of the message before processing them.

419

</para>

420

<para>

421

A word is reflected or reversed by <quote>flipping</quote> its bits around the

422

mid-point of the word.

423

The most significant bit of the word is moved to the least significant position,

424

the second-most significant bit is moved to the second-least significant position

425

and so on.

426

The reflected value of 0xa2 (10100010b) is 0x45 (01000101b), for example.

427

</para>

428

<para>

429

Some CRC algorithms can be implemented more efficiently in a bit reversed version,

430

that's why many of the standard CRC models use reflected input octets.

</para>

</glossdef>

</glossentry>

<para>

The initial value (usually all 0 or all 1) for algorithms which operate on the

439

non-augmented message, that is, any algorithm other than the

440

<replaceable>&bit-by-bit;</replaceable> one.

441

This value can be interpreted as a value which will be XOR-ed into the CRC register

442

after <replaceable>&width;</replaceable> iterations of the

443

<replaceable>&bit-by-bit;</replaceable> algorithm.

444

This implies that the simple <replaceable>&bit-by-bit;</replaceable> algorithm must

445

calculate the initial value using some sort of reverse CRC algorithm on the

446

<replaceable>&xor_in;</replaceable> value.

</para>

</glossdef>

</glossentry>

<glossterm><replaceable>&reflect_out;</replaceable></glossterm>

452

453

<para>

454

Reflect the final CRC result. This operation takes place before XOR-ing the final CRC

455

value with the <replaceable>&xor_out;</replaceable> parameter.

</para>

</glossdef>

</glossentry>

<para>

A value (usually all bits 0 or all 1) which will be XOR-ed to the final CRC value.

</para>

</glossdef>

</glossentry>

<glossterm><replaceable>&check;</replaceable></glossterm>

469

470

<para>

471

This value is not exactly a parameter of a model but it is sometimes given together

472

with the Rocksoft Model parameters.

473

It is the CRC value of the parametrised model over the string

474

<quote><replaceable>123456789</replaceable></quote> and

475

can be used as a sanity check for a particular CRC implementation.

</para>

</glossdef>

</glossentry>

</glosslist>

</para>

</refsect1>

<title>Code generation</title>

485

<para>

486

In the default configuration, the generated code is strict ISO C99.

487

A minimal set of three functions are defined for each algorithm:

488

<function>crc_init()</function>, <function>crc_update()</function> and <function>crc_finalize()</function>.

489

Depending on the number of parameters given to pycrc, a different interface will be defined.

490

A fully parametrised model has a simpler API, while the generated code for a runtime-specified

491

implementation requires a pointer to a configuration structure as first parameter to all functions.

492

</para>

493

<para>

494

The generated source code uses the type <type>crc_t</type>, which is used throughout the code

495

to hold intermediate results and also the final CRC value.

496

It is defined in the generated header file and its type may be overridden with the

497

<option>--crc-type</option> option.

498

</para>

499

500

<refsect2><title>Fully parametrised models</title>

501

<para>

502

The prototypes of the CRC functions are normally generated by pycrc using the

503

<replaceable>--generate h</replaceable> option.

504

The CRC functions for a fully parametrised model will look like:

</para>

#include <stdlib.h>

typedef uint16_t crc_t; /* pycrc will use an appropriate size here */

510

</funcsynopsisinfo>

511

512

<?dbhtml funcsynopsis-style='ansi'?>

<void/>

</funcprototype>

<?dbhtml funcsynopsis-style='ansi'?>

519

<funcdef>crc_t <function>crc_update</function></funcdef>

520

521

<paramdef>const unsigned char *<parameter>data</parameter></paramdef>

</funcprototype>

<?dbhtml funcsynopsis-style='ansi'?>

527

<funcdef>crc_t <function>crc_finalize</function></funcdef>

</funcprototype>

</funcsynopsis>

<para>

The code snippet below shows how to use the generated functions.

534

535

#include "pycrc_generated_crc.h"

#include <stdio.h>

int main(void)

{

static const unsigned char str1[] = "1234";

541

static const unsigned char str2[] = "56789";

crc_t crc;

crc = crc_init();

crc = crc_update(crc, str1, sizeof(str1) - 1);

546

crc = crc_update(crc, str2, sizeof(str2) - 1);

547

/* more calls to crc_update... */

548

crc = crc_finalize(crc);

549

550

printf("0x%lx\n", (long)crc);

return 0;

}

</programlisting>

</para>

</refsect2>

<title>Models with runtime-configurable parameters</title>

559

<para>

560

When the model is not fully defined then the missing parameters are stored in a structure of

561

type <type>crc_cfg_t</type>.

562

If a CRC function requires a value from the <type>crc_cfg_t</type> structure, then the first

563

function argument is always a pointer to that structure.

564

All fields of the configuration structure must be properly initialised before the first call

to any CRC function.

</para>

<para>

If the <replaceable>&width;</replaceable> was not specified when the code was generated, then

569

the <type>crc_cfg_t</type> structure will contain three more fields:

570

<parameter>msb_mask</parameter>, <parameter>crc_mask</parameter> and <parameter>crc_shift</parameter>.

571

They are defined for performance reasons and must be initialised to the value given next to the

field definition.

</para>

<para>

For example, a completely undefined CRC implementation will generate a <type>crc_cfg_t</type>

structure as below:

typedef struct {

unsigned int width;

crc_t poly;

bool reflect_in;

crc_t xor_in;

bool reflect_out;

crc_t xor_out;

// internal parameters

587

crc_t msb_mask; // initialise as (crc_t)1u << (cfg->width - 1)

588

crc_t crc_mask; // initialise as (cfg->msb_mask - 1) | cfg->msb_mask

589

unsigned int crc_shift; // initialise as cfg->width < 8 ? 8 - cfg->width : 0

} crc_cfg_t;

</programlisting>

</para>

<para>

<parameter>msb_mask</parameter> is a bitmask with the most significant bit of a

595

<replaceable>&width;</replaceable> bits wide data type set to 1.

596

597

<parameter>crc_mask</parameter> is a bitmask with all bits of a

598

<replaceable>&width;</replaceable> bits wide data type set to 1.

599

600

<parameter>crc_shift</parameter> is a shift counter that is used when

601

<replaceable>&width;</replaceable> is less than 8.

602

It is the number of bits to shift the CRC register to align its top bit to a byte boundary.

</para>

<para>

The file <filename>test/main.c</filename> in the source package of pycrc

607

contains a fully featured example of how to use the generated source code.

608

A shorter, more compact <code>main()</code> function can be generated with the

609

<replaceable>--generate c-main</replaceable> option.

610

This second variant is the better option as it will always output valid code when

611

some of the CRC parameters are known and some are unknown during code generation.

</para>

</refsect2>

</refsect1>

<refsect1><title>Examples</title>

<para>

<glossterm>Calculate the CRC-32 checksum of the string <quote>123456789</quote>:</glossterm>

621

622

<para>

623

<userinput>python pycrc.py --model crc-32 --check-string 123456789</userinput>

</para>

</glossdef>

</glossentry>

<glossterm>Generate the source code of the table-driven algorithm for an embedded application.</glossterm>

629

630

<para>

631

The table index width of 4 bits ensures a moderate memory usage.

632

To be precise, the size of the resulting table will be <code>16 * sizeof(crc_t)</code>.

633

</para>

634

<para>

635

<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate h -o crc.h</userinput>

636

</para>

637

<para>

638

<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c -o crc.c</userinput>

639

</para>

640

<para>

641

A variant of the <replaceable>c</replaceable> target is <replaceable>c-main</replaceable>:

642

this target will generate a simple <replaceable>main()</replaceable> function in addition to

the CRC functions:

</para>

<para>

<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c-main -o crc.c</userinput>

</para>

</glossdef>

</glossentry>

<glossterm>Generate the CRC table only:</glossterm>

652

653

<para>

654

<userinput>python pycrc.py --model kermit --generate table -o crc-table.txt</userinput>

</para>

</glossdef>

</glossentry>

</glosslist>

</para>

</refsect1>

<para>

The homepage of pycrc is <link xlink:href="&project_homepage;">&project_homepage;</link>.

666

</para>

667

<para>

668

A list of common CRC models is at <link xlink:href="&project_models;">&project_models;</link>.

669

For a long list of known CRC models, see Greg Cook's

</para>

</refsect1>

<title>Copyright</title>

676

<para>

677

This work is licensed under a

</para>

</refsect1>

</refentry>