summaryrefslogtreecommitdiff
path: root/cesar/lib/crc.h
diff options
context:
space:
mode:
authorschodet2008-06-03 13:27:00 +0000
committerschodet2008-06-03 13:27:00 +0000
commit5c79d32182b16a81459229d58396fc66461c9e51 (patch)
tree4dc0b62258210422b9eb2c10b3e5b3834ae559ef /cesar/lib/crc.h
parent66376099c807f167a554767a4b3fa2fe35978fed (diff)
* lib:
- added CRC doc. git-svn-id: svn+ssh://pessac/svn/cesar/trunk@2208 017c9cb6-072f-447c-8318-d5b54f68fe89
Diffstat (limited to 'cesar/lib/crc.h')
-rw-r--r--cesar/lib/crc.h63
1 files changed, 59 insertions, 4 deletions
diff --git a/cesar/lib/crc.h b/cesar/lib/crc.h
index 76f4501949..7f3b3574be 100644
--- a/cesar/lib/crc.h
+++ b/cesar/lib/crc.h
@@ -12,23 +12,74 @@
* \brief General Cyclic Redundancy Code utilities.
* \ingroup lib
*
+ * General CRC utilities
+ * =====================
+ *
* This module follows the Rocksoft^tm Model CRC Algorithm, introduced in "A
* painless guide to CRC error detection algorithms" by Ross N. Williams. You
- * can get it at http://www.ross.net/crc/.
+ * can get it at http://www.ross.net/crc/. This model defines a nomenclature
+ * of existing CRC implementations in order to fully specify a CRC algorithm.
+ * This module takes parameters from this model as input to generate the
+ * requested CRC generator.
*
* Once you got a functional CRC algorithm, you also have to take care of
* details such as:
+ *
* - bit and byte order of the CRC digest,
* - whether extra zeros must be added to the message (this could be
- * precomputed in crc_init),
+ * precomputed in crc_init),
* - what is the expected CRC result if feeding the algorithms with the
- * message along with the appended CRC digest.
+ * message along with the appended CRC digest.
+ *
+ * Usage
+ * =====
+ *
+ * To use this module, you should first call \c crc_init with your CRC
+ * algorithm description and some extra memory. This will construct a lookup
+ * table to speed-up future computations.
+ *
+ * Example:
+ *
+ * \code
+ * static u32 crc32_tab[256];
+ * static crc_t crc32;
+ * crc32.width = 32;
+ * crc32.generator = 0x04c11db7;
+ * crc32.init = 0xffffffff;
+ * crc32.refin = true;
+ * crc32.refout = true;
+ * crc32.xorout = 0xffffffff;
+ * crc32.table.t32 = crc32_tab;
+ * crc_init (&crc32);
+ * \endcode
+ *
+ * The table should be a 256 wide table of u32, u16 or u8, depending on the
+ * CRC width. You should store a pointer to it in \c table.t32, \c table.t16
+ * or \c table.t8.
*
* CRC tables might be shared between several algorithms but this is an
* unsupported feature, use at your own risk (basically, any parameters used
* to initialise the table must be the same between the sharing algorithms).
* If you play this game, remember that there is more than the table to
* contain precomputed values.
+ *
+ * Once your CRC description is initialised, you can use it to compute CRC.
+ * Initialisation should be done only once in your program life as the table
+ * construction is expensive.
+ *
+ * You have two options to compute your CRC. If the whole buffer is available
+ * and linear, you can use \c crc_compute_block to compute the CRC in one
+ * pass. If the whole input buffer is not available yet or is sliced in
+ * several non linear buffers, you should use \c crc_compute_begin to
+ * initialise the CRC computation, \c crc_compute_continue_block for each
+ * input blocks, and finally \c crc_compute_end to stop the computation and
+ * retrieve the final CRC value.
+ *
+ * There is also a \c ..._le version of \c crc_compute_block and
+ * \c crc_compute_continue_block which read input buffer using word access and
+ * process read data as little endian.
+ *
+ * There is no big endian version as there is no demand for it for the moment.
*/
/** CRC description structure. */
@@ -68,6 +119,8 @@ struct crc_t
};
typedef struct crc_t crc_t;
+BEGIN_DECLS
+
/**
* Compute precomputed values for the given CRC characteristics.
* \param ctx filled CRC description
@@ -132,10 +185,12 @@ crc_compute_continue_block_le (const crc_t *ctx, u32 reg, const u8 *block,
/**
* End a CRC computation.
* \param ctx initialised CRC description
- * \param reg previously used CRC register
+ * \param reg previously used CRC register
* \return computed CRC
*/
u32
crc_compute_end (const crc_t *ctx, u32 reg);
+END_DECLS
+
#endif /* lib_crc_h */