From 07aa41e6efad2cbc79a8269b114fe7eab0c330bf Mon Sep 17 00:00:00 2001
From: "Devin J. Pohly" <djpohly@gmail.com>
Date: Sun, 12 Aug 2012 23:13:34 -0400
Subject: [PATCH] add comments to clarify piuio inputdriver

---
 .../InputHandler/InputHandler_Linux_PIUIO.cpp | 34 +++++++++++++++++--
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/src/arch/InputHandler/InputHandler_Linux_PIUIO.cpp b/src/arch/InputHandler/InputHandler_Linux_PIUIO.cpp
index c57e7dd4d6..1febef3722 100644
--- a/src/arch/InputHandler/InputHandler_Linux_PIUIO.cpp
+++ b/src/arch/InputHandler/InputHandler_Linux_PIUIO.cpp
@@ -4,6 +4,7 @@
 #include "RageUtil.h"
 
 #include <stdio.h>
+#include <string.h>
 #include <unistd.h>
 #include <fcntl.h>
 
@@ -19,6 +20,7 @@ InputHandler_Linux_PIUIO::InputHandler_Linux_PIUIO()
 {
 	LOG->Trace( "InputHandler_Linux_PIUIO::InputHandler_Linux_PIUIO" );
 
+	// Open device file and make sure it's actually a device...
 	fd = open( "/dev/piuio0", O_RDONLY );
 	if( fd < 0 )
 	{
@@ -43,6 +45,7 @@ InputHandler_Linux_PIUIO::InputHandler_Linux_PIUIO()
 
 	LOG->Info("Opened PIUIO device for input");
 
+	// Set up a flag we can use to stop the input thread gracefully
 	m_bShutdown = false;
 
 	m_InputThread.SetName( "PIUIO thread" );
@@ -51,12 +54,13 @@ InputHandler_Linux_PIUIO::InputHandler_Linux_PIUIO()
 
 InputHandler_Linux_PIUIO::~InputHandler_Linux_PIUIO()
 {
+	// Shut down the thread if it's running
 	if( m_InputThread.IsCreated() )
 	{
 		m_bShutdown = true;
 		LOG->Trace( "Shutting down PIUIO thread ..." );
 		m_InputThread.Wait();
-		LOG->Trace( "PIUIO thread shut down." );
+		LOG->Info( "PIUIO thread shut down." );
 	}
 
 	if (fd >= 0)
@@ -74,6 +78,14 @@ void InputHandler_Linux_PIUIO::InputThread()
 	unsigned char inputs[32];
 	while( !m_bShutdown )
 	{
+		// To get input from the PIUIO driver, just read from the
+		// device.  This returns 32 bytes:
+		//   8 bytes/64 bits - first set of sensors (e.g. top sensor in
+		//                                           each panel)
+		//   8 bytes/64 bits - second set of sensors
+		//   8 bytes/64 bits - third set of sensors
+		//   8 bytes/64 bits - fourth set of sensors
+
 		int ret = read(fd, &inputs, sizeof(inputs));
 		if (ret != sizeof(inputs))
 		{
@@ -84,17 +96,33 @@ void InputHandler_Linux_PIUIO::InputThread()
 
 		InputDevice id = InputDevice(DEVICE_JOY1);
 
+		// The device reads *low* for an input that's pressed.  So to
+		// combine the data from the sensors, we AND them together; if
+		// any sensor was pressed (0), the result will show pressed (0).
+		// Here we combine the second, third, and fourth sensors into
+		// the first set.
 		int i;
 		for (i = 8; i < 32; i++)
 			inputs[i % 8] &= inputs[i];
+
+		// To figure out if anything has changed since the last time we
+		// read input, we XOR the current readings with the previous
+		// readings.
 		for (i = 0; i < 8; i++)
 			lastInputs[i] ^= inputs[i];
+
+		// Iterate through the first 64 bits of the array one at a time,
+		// and generate an event for each one that has changed.
 		for (i = 0; i < 64; i++)
+			// Bit is set = status changed
 			if (lastInputs[i / 8] & (128 >> (i % 8)))
+				// Make a "pressed" event if the current reading
+				// is 0, and a "released" event if it's 1.
 				ButtonPressed(DeviceInput(id, enum_add2(JOY_BUTTON_1, i),
 						!(inputs[i / 8] & (128 >> (i % 8))), now));
-		for (i = 0; i < 8; i++)
-			lastInputs[i] = inputs[i];
+
+		// Save the current reading to use next time
+		memcpy(lastInputs, inputs, sizeof(lastInputs));
 	}
 
 	InputHandler::UpdateTimer();