add enable/disable for yield calls (#20)

* add enable/disable yield() * update documentation
RobTillaart · Feb 8, 2022 · 794a8fb · 794a8fb
1 parent 836672c
commit 794a8fb
Show file tree

Hide file tree

Showing 16 changed files with 77 additions and 13 deletions.
diff --git a/CRC.h b/CRC.h
@@ -2,7 +2,7 @@
 //
 //    FILE: CRC.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.1
+// VERSION: 0.2.2
 // PURPOSE: Arduino library for CRC8, CRC12, CRC16, CRC16-CCITT, CRC32, CRC64
 //     URL: https://github.com/RobTillaart/CRC
 //
@@ -12,7 +12,7 @@
 
 #include "CRC_polynomes.h"
 
-#define CRC_LIB_VERSION       (F("0.2.1"))
+#define CRC_LIB_VERSION       (F("0.2.2"))
 
 
 ////////////////////////////////////////////////////////////////

diff --git a/CRC12.cpp b/CRC12.cpp
@@ -24,6 +24,7 @@ void CRC12::reset()
   _reverseOut = false;
   _started    = false;
   _count      = 0;
+  _canYield   = true;
 }
 
 
@@ -38,7 +39,7 @@ void CRC12::restart()
 void CRC12::add(uint8_t value)
 {
   _count++;
-  if ((_count & 0xFF) == 0) yield();
+  if (_canYield && ((_count & 0xFF) == 0)) yield();
   _update(value);
 }
 

diff --git a/CRC12.h b/CRC12.h
@@ -41,6 +41,10 @@ class CRC12
   uint16_t getCRC();  // returns CRC
   uint32_t count()    { return _count; };
 
+  // POWER USER ONLY
+  void     enableYield()  { _canYield = true; };
+  void     disableYield() { _canYield = false; };
+
 private:
   uint16_t _reverse(uint16_t value);
   uint8_t  _reverse8(uint8_t value);
@@ -53,6 +57,7 @@ class CRC12
   bool     _reverseIn;
   bool     _reverseOut;
   bool     _started;
+  bool     _canYield;
   uint32_t _count;
 };
 

diff --git a/CRC16.cpp b/CRC16.cpp
@@ -24,6 +24,7 @@ void CRC16::reset()
   _reverseOut = false;
   _started    = false;
   _count      = 0;
+  _canYield   = true;
 }
 
 
@@ -38,7 +39,7 @@ void CRC16::restart()
 void CRC16::add(uint8_t value)
 {
   _count++;
-  if ((_count & 0xFF) == 0) yield();
+  if (_canYield && ((_count & 0xFF) == 0)) yield();
   _update(value);
 }
 

diff --git a/CRC16.h b/CRC16.h
@@ -40,6 +40,10 @@ class CRC16
   uint16_t getCRC();  // returns CRC
   uint32_t count()    { return _count; };
 
+  // POWER USER ONLY
+  void     enableYield()  { _canYield = true; };
+  void     disableYield() { _canYield = false; };
+
 private:
   uint16_t _reverse(uint16_t value);
   uint8_t  _reverse8(uint8_t value);
@@ -52,6 +56,7 @@ class CRC16
   bool     _reverseIn;
   bool     _reverseOut;
   bool     _started;
+  bool     _canYield;
   uint32_t _count;
 };
 

diff --git a/CRC32.cpp b/CRC32.cpp
@@ -24,6 +24,7 @@ void CRC32::reset()
   _reverseOut = false;
   _started    = false;
   _count      = 0;
+  _canYield   = true;
 }
 
 
@@ -38,7 +39,7 @@ void CRC32::restart()
 void CRC32::add(uint8_t value)
 {
   _count++;
-  if ((_count & 0xFF) == 0) yield();
+  if (_canYield && ((_count & 0xFF) == 0)) yield();
   _update(value);
 }
 

diff --git a/CRC32.h b/CRC32.h
@@ -40,6 +40,10 @@ class CRC32
   uint32_t getCRC();  // returns CRC
   uint32_t count()    { return _count; };
 
+  // POWER USER ONLY
+  void     enableYield()  { _canYield = true; };
+  void     disableYield() { _canYield = false; };
+
 private:
   uint32_t _reverse(uint32_t value);
   uint8_t  _reverse8(uint8_t value);
@@ -52,6 +56,7 @@ class CRC32
   bool     _reverseIn;
   bool     _reverseOut;
   bool     _started;
+  bool     _canYield;
   uint32_t _count;
 };
 

diff --git a/CRC64.cpp b/CRC64.cpp
@@ -24,6 +24,7 @@ void CRC64::reset()
   _reverseOut = false;
   _started    = false;
   _count      = 0;
+  _canYield   = true;
 }
 
 
@@ -38,7 +39,7 @@ void CRC64::restart()
 void CRC64::add(uint8_t value)
 {
   _count++;
-  if ((_count & 0xFF) == 0) yield();
+  if (_canYield && ((_count & 0xFF) == 0)) yield();
   _update(value);
 }
 

diff --git a/CRC64.h b/CRC64.h
@@ -41,6 +41,10 @@ class CRC64
   uint64_t getCRC();  // returns CRC
   uint64_t count()    { return _count; };
 
+  // POWER USER ONLY
+  void     enableYield()  { _canYield = true; };
+  void     disableYield() { _canYield = false; };
+
 private:
   uint64_t _reverse(uint64_t value);
   uint8_t  _reverse8(uint8_t value);
@@ -53,6 +57,7 @@ class CRC64
   bool     _reverseIn;
   bool     _reverseOut;
   bool     _started;
+  bool     _canYield;
   uint64_t _count;
 };
 

diff --git a/CRC8.cpp b/CRC8.cpp
@@ -38,7 +38,7 @@ void CRC8::restart()
 void CRC8::add(uint8_t value)
 {
   _count++;
-  if ((_count & 0xFF) == 0) yield();
+  if (_canYield && ((_count & 0xFF) == 0)) yield();
   _update(value);
 }
 

diff --git a/CRC8.h b/CRC8.h
@@ -40,6 +40,10 @@ class CRC8
   uint8_t  getCRC();  // returns CRC
   uint32_t count()    { return _count; };
 
+  // POWER USER ONLY
+  void     enableYield()  { _canYield = true; };
+  void     disableYield() { _canYield = false; };
+
 private:
   uint8_t  _reverse(uint8_t value);
   void     _update(uint8_t value);
@@ -51,6 +55,7 @@ class CRC8
   bool     _reverseIn;
   bool     _reverseOut;
   bool     _started;
+  bool     _canYield;
   uint32_t _count;
 };
 

diff --git a/README.md b/README.md
@@ -76,6 +76,23 @@ These parameters do not have defaults so the user must set them explicitly.
 - **bool getReverseOut()** return parameter set above or default.
 
 
+#### power users only
+
+As CRC calculations of large blocks can take serious time (in milliseconds),
+the classes call **yield()** after every 256 **add()** calls to keep RTOS
+environments happy. 
+
+The following two calls allows one to enable and disable these calls to 
+**yield()** to get optimal performance. The risk is missing context switching
+to handle interrupts etc. So use at own risk.
+
+- **void enableYield()** enables the calls to **yield()**.
+- **void disableYield()** disables the calls to **yield()**.
+
+_Note: the static functions in this library also call **yield()** but this 
+cannot be disabled (for now)._
+
+
 ### Example snippet
 
 A minimal usage only needs: 
@@ -107,15 +124,17 @@ For flexibility both parameters are kept available.
 
 - **uint8_t crc8(array, length, polynome = 0xD5, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
 - **uint16_t crc12(array, length, polynome = 0x080D, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
-- **uint16_t crc16(array, length, polynome = 0xA001, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
+- **uint16_t crc16(array, length, polynome = 0x8001, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
 - **uint16_t crc16-CCITT(array, length)** fixed polynome **0x1021**, non zero start / end masks.
 - **uint32_t crc32(array, length, polynome = 0x04C11DB7, start = 0, end = 0, reverseIn = false, reverseOut = false)** idem with default polynome.
 - **uint64_t crc64(array, length, polynome = 0x42F0E1EBA9EA3693, start = 0, end = 0, reverseIn = false, reverseOut = false)** - experimental version, no reference found except on Wikipedia.
 
-Note these functions are limited to one call per block of data. For more flexibility use the classes.
+Note these functions are limited to one call per block of data. 
+These functions will call **yield()** every 256 bytes to keep RTOS happy.
+For more flexibility use the specific classes.
 
-The CRC functions also have fast reverse functions that can be used outside CRC context.
-The usage is straightforward.
+The static CRC functions use fast reverse functions that can be also be 
+used outside CRC context. Their usage is straightforward.
 
 - **uint8_t reverse8(uint8_t in)** idem.
 - **uint16_t reverse16(uint16_t in)** idem.
@@ -127,6 +146,13 @@ Reverse12 is based upon reverse16, with a final shift.
 Other reverses can be created in similar way.
 
 
+## CRC_polynomes.h
+
+Since version 0.2.1 the file CRC_polynomes.h is added to hold symbolic names for certain polynomes.
+These can be used in your code too to minimize the number of "magic HEX codes".
+If standard polynomes are missing, please open an issue and report, with reference.
+
+
 ## Operational
 
 See examples.

diff --git a/keywords.txt b/keywords.txt
@@ -34,6 +34,10 @@ add	KEYWORD2
 getCRC	KEYWORD2
 count	KEYWORD2
 
+enableYield	KEYWORD2
+disableYield	KEYWORD2
+
+
 # Instances (KEYWORD2)
 
 

diff --git a/library.json b/library.json
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/CRC"
   },
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=CRC
-version=0.2.1
+version=0.2.2
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Library for CRC for Arduino

diff --git a/releaseNotes.md b/releaseNotes.md
@@ -2,6 +2,11 @@
 # Release Notes
 
 
+## 0.2.2
+
+- fix #19 enable/disable yield call
+
+
 ## 0.2.1
 
 - fix #17 yield() count in **add(array, length)**