X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fcrc.h;h=73363ddb77ca17ea91552a85b177a18ecdf04917;hb=244c4fe7e6cf5ae78cbe6343fe7f9b6dfc29b11a;hp=0e3d0137c20858fe775cec9afe30116e850dd107;hpb=497d58b96ab7e962dd53527ae0ed07c52680fea4;p=libucw.git

diff --git a/ucw/crc.h b/ucw/crc.h
index 0e3d0137..73363ddb 100644
--- a/ucw/crc.h
+++ b/ucw/crc.h
@@ -16,7 +16,10 @@
  *	Adapted for LibUCW by Martin Mares <mj@ucw.cz> in 2012.
  */
 
-/*
+#ifndef _UCW_CRC_H
+#define _UCW_CRC_H
+
+/**
  * Internal CRC calculator context.
  * You should use it just as an opaque handle only.
  */
@@ -25,23 +28,45 @@ typedef struct crc32_context {
   void (*update_func)(struct crc32_context *ctx, const byte *buf, uns len);
 } crc32_context;
 
+/**
+ * Initialize new calculation of CRC in a given context.
+ * @crc_mode selects which algorithm should be used.
+ **/
 void crc32_init(crc32_context *ctx, uns crc_mode);
 
+/**
+ * Algorithm used for CRC calculation. The algorithms differ by the amount
+ * of precomputed tables they use. Bigger tables imply faster calculation
+ * at the cost of an increased cache footprint.
+ **/
 enum crc_mode {
-  CRC_MODE_DEFAULT,
-  CRC_MODE_SMALL,
-  CRC_MODE_BIG,
+  CRC_MODE_DEFAULT,		/* Default algorithm (4K table) */
+  CRC_MODE_SMALL,		/* Optimize for small data (1K table) */
+  CRC_MODE_BIG,			/* Optimize for large data (8K table) */
   CRC_MODE_MAX,
 };
 
-static inline void
-crc32_update(crc32_context *ctx, const byte *buf, uns len)
+/** Feed @len bytes starting at @buf to the CRC calculator. **/
+static inline void crc32_update(crc32_context *ctx, const byte *buf, uns len)
 {
   ctx->update_func(ctx, buf, len);
 }
 
-static inline u32
-crc32_final(crc32_context *ctx)
+/** Finish calculation and return the CRC value. **/
+static inline u32 crc32_final(crc32_context *ctx)
 {
   return ctx->state ^ 0xffffffff;
 }
+
+/**
+ * A convenience one-shot function for CRC.
+ * It is equivalent to this snippet of code:
+ *
+ *  crc32_context ctx;
+ *  crc32_init(&ctx, CRC_MODE_DEFAULT);
+ *  crc32_update(&ctx, buf, len);
+ *  return crc32_final(&ctx);
+ */
+u32 crc32_hash_buffer(const byte *buf, uns len);
+
+#endif