Merge pull request #3 from RobTillaart/develop

refactor documentation; fix tabs -> spaces

Author: RobTillaart

FastShiftIn.cpp

@@ -4,109 +4,108 @@
 // VERSION: 0.2.1
 // PURPOSE: Fast ShiftIn for 74HC165 register, AVR optimized
 //    DATE: 2013-09-29
-//     URL: https://github.com/RobTillaart/FastShiftIn.git
+//     URL: https://github.com/RobTillaart/FastShiftIn
 //
 
 #include "FastShiftIn.h"
 
 FastShiftIn::FastShiftIn(const uint8_t datapin, const uint8_t clockpin, const uint8_t bitOrder)
 {
-    _bitorder = bitOrder;
+  _bitorder = bitOrder;
 
-    pinMode(datapin, INPUT);
-    pinMode(clockpin, OUTPUT);
+  pinMode(datapin, INPUT);
+  pinMode(clockpin, OUTPUT);
 
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 
-    // uint8_t _datatimer  = digitalPinToTimer(datapin);
-    // if (_datatimer != NOT_ON_TIMER) turnOffPWM(_datatimer); TODO
-    uint8_t _dataport   = digitalPinToPort(datapin);
-    _datain = portOutputRegister(_dataport);
-    _databit = digitalPinToBitMask(datapin);
+  // uint8_t _datatimer  = digitalPinToTimer(datapin);
+  // if (_datatimer != NOT_ON_TIMER) turnOffPWM(_datatimer); TODO
+  uint8_t _dataport   = digitalPinToPort(datapin);
+  _datain = portOutputRegister(_dataport);
+  _databit = digitalPinToBitMask(datapin);
 
-    // uint8_t _clocktimer = digitalPinToTimer(clockpin);
-    // if (_clocktimer != NOT_ON_TIMER) turnOffPWM(_clocktimer);
-    uint8_t _clockport  = digitalPinToPort(clockpin);
-    _clockin = portOutputRegister(_clockport);
-    _clockbit = digitalPinToBitMask(clockpin);
+  // uint8_t _clocktimer = digitalPinToTimer(clockpin);
+  // if (_clocktimer != NOT_ON_TIMER) turnOffPWM(_clocktimer);
+  uint8_t _clockport  = digitalPinToPort(clockpin);
+  _clockin = portOutputRegister(_clockport);
+  _clockbit = digitalPinToBitMask(clockpin);
 
 #else   // reference implementation
 
-	// reuse these vars as pin to save some space
-    _databit = datapin;
-    _clockbit = clockpin;
+  // reuse these vars as pin to save some space
+  _databit = datapin;
+  _clockbit = clockpin;
 
 #endif
 }
 
 int FastShiftIn::read()
 {
-    if (_bitorder == LSBFIRST)
-	{
-		return readLSBFIRST();
-	}
-	return readMSBFIRST();
+  if (_bitorder == LSBFIRST)
+  {
+    return readLSBFIRST();
+  }
+  return readMSBFIRST();
 }
 
 #if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_MEGAAVR)
 
 int FastShiftIn::readLSBFIRST()
 {
-    uint8_t value = 0;
-	uint8_t cbmask1 = _clockbit;
-	uint8_t cbmask2 = ~_clockbit;
-	uint8_t dbmask = _databit;
-
-	for (uint8_t m = 1; m > 0; m <<= 1)
-	{
-		uint8_t oldSREG = SREG;
-		cli();
-		*_clockin |= cbmask1;
-		if ((*_datain & dbmask) > 0)
-		{
-			value |= m;
-		}
-		*_clockin &= cbmask2;
-		SREG = oldSREG;
-	}
-    _value = value;
-    return _value;
+  uint8_t value = 0;
+  uint8_t cbmask1 = _clockbit;
+  uint8_t cbmask2 = ~_clockbit;
+  uint8_t dbmask = _databit;
+
+  for (uint8_t m = 1; m > 0; m <<= 1)
+  {
+    uint8_t oldSREG = SREG;
+    cli();
+    *_clockin |= cbmask1;
+    if ((*_datain & dbmask) > 0)
+    {
+      value |= m;
+    }
+    *_clockin &= cbmask2;
+    SREG = oldSREG;
+  }
+  _value = value;
+  return _value;
 }
 
 int FastShiftIn::readMSBFIRST()
 {
-    uint8_t value = 0;
-	uint8_t cbmask1 = _clockbit;
-	uint8_t cbmask2 = ~cbmask1;
-	uint8_t dbmask = _databit;
-
-	for (uint8_t n = 128; n > 0; n >>= 1)
-	{
-		uint8_t oldSREG = SREG;
-		cli();
-		*_clockin |= cbmask1;
-	
-		if ((*_datain & dbmask) > 0)
-		{
-			value |= n;
-		}
-		*_clockin &= cbmask2;
-		SREG = oldSREG;
-	}
-    _value = value;
-    return _value;
+  uint8_t value = 0;
+  uint8_t cbmask1 = _clockbit;
+  uint8_t cbmask2 = ~cbmask1;
+  uint8_t dbmask = _databit;
+
+  for (uint8_t n = 128; n > 0; n >>= 1)
+  {
+    uint8_t oldSREG = SREG;
+    cli();
+    *_clockin |= cbmask1;
+    if ((*_datain & dbmask) > 0)
+    {
+      value |= n;
+    }
+    *_clockin &= cbmask2;
+    SREG = oldSREG;
+  }
+  _value = value;
+  return _value;
 }
 
-#else  // reference implementation  // note this has no cli()
+#else  // reference implementation - note this has no cli()
 
 int FastShiftIn::readLSBFIRST()
 {
-	return shiftIn(_databit, _clockbit, LSBFIRST);
+  return shiftIn(_databit, _clockbit, LSBFIRST);
 }
 
 int FastShiftIn::readMSBFIRST()
 {
-	return shiftIn(_databit, _clockbit, MSBFIRST);
+  return shiftIn(_databit, _clockbit, MSBFIRST);
 }
 
 #endif

FastShiftIn.h

@@ -5,7 +5,7 @@
 // VERSION: 0.2.1
 // PURPOSE: Fast ShiftIn for 74HC165 register, AVR optimized
 //    DATE: 2013-09-29
-//     URL: https://github.com/RobTillaart/FastShiftIn.git
+//     URL: https://github.com/RobTillaart/FastShiftIn
 //
 
 #include "Arduino.h"
@@ -15,23 +15,23 @@
 class FastShiftIn
 {
 public:
-    // bitorder = { LSBFIRST, MSBFIRST };
-    FastShiftIn(const uint8_t datapin, const uint8_t clockpin, const uint8_t bitOrder = LSBFIRST);
-    int read(void);
-	
-	// overrule bitorder (most optimized).
-    int readLSBFIRST(void);
-    int readMSBFIRST(void);
+  // bitorder = { LSBFIRST, MSBFIRST };
+  FastShiftIn(const uint8_t datapin, const uint8_t clockpin, const uint8_t bitOrder = LSBFIRST);
+  int read(void);
+
+  // overrule bitorder (most optimized).
+  int readLSBFIRST(void);
+  int readMSBFIRST(void);
 
 private:
-    uint8_t _bitorder;
-    int _value;
+  uint8_t _bitorder;
+  int _value;
 
-    uint8_t _databit;
-    volatile uint8_t *_datain;
+  uint8_t _databit;
+  volatile uint8_t *_datain;
 
-    uint8_t _clockbit;
-    volatile uint8_t *_clockin;
+  uint8_t _clockbit;
+  volatile uint8_t *_clockin;
 };
 
 // -- END OF FILE --

README.md

@@ -6,22 +6,34 @@ A library for FastShiftOut also exist.
 
 ## Description
 
-FastShiftIn is a class that speeds up the shifting of the bits by using predetermined ports and masks. 
-These are predetermined inthe constructor of the FastShiftIN object.
+FastShiftIn is a class that has optimized code (AVR only) to shift in data faster 
+than the normal shiftIn() function.
+It speeds up the shift using low level ports and masks. These are predetermined
+in the constructor of the FastShiftIn object.
 
-The performance of **read()** is substantially faster than the default Arduino **shiftIn()**, 
-but not as fast as HW SPI. Exact how big the performance gain is can be seen with the example sketch.
+If not an **ARDUINO_ARCH_AVR** or **ARDUINO_ARCH_MEGAAVR** the class falls back 
+to the default shiftIn() implementation.
+
+## Performance
+
+The performance of **read()** is substantially faster than the default Arduino 
+**shiftIn()**, but not as fast as HW SPI. 
+Exact how big the performance gain is can be seen with the example sketch.
 It does a comparison and shows how the class is to be used.
 
-Version 0.2.0 added **readLSBFIRST()** and **readMSBFIRST()** to squeeze max performance. 
-The next stop might be assembly.
+## Interface
+
+The interface exists of the following functions:
+
+- **int read(void);**
+- **int readLSBFIRST(void);**  most optimized
+- **int readMSBFIRST(void);**  most optimized
 
-**Note**
-The optimizations are AVR only for now, other platforms may follow.
+## Notes
 
-**Note** 
-The 74HC165 needs 0.1uF caps and the data and clock lines 
-may need pull up resistors, especially if wires are exceeding 10 cm (4").
+- The optimizations are AVR only for now, other platforms may follow.
+- The 74HC165 needs 0.1uF caps and the data and clock lines may need  
+pull up resistors, especially if wires are exceeding 10 cm (4").
 
 ## Operation