Add finger present API and bit. Update README

Signed-off-by: Joachim Strömbergson <[email protected]>

Author: secworks

hw/application_fpga/core/touch_sense/README.md

@@ -16,14 +16,27 @@ before being able to detect another event.
 
 
 ## API
-
-The API has a single address, and a single bit in that address:
+The API has two addresses.
 
 ```
 	ADDR_STATUS: 0x09
 	STATUS_EVENT_BIT: 0
+
+	ADDR_PRESENT: 0x0a
+	FINGER_PRESENT_BIT: 0
 ```
 
-SW should clear any stray attempts before signalling to the user that
-a touch event is expected. Clearing an event is done by writing the
-the status address, the value written does not matter.
+In order to detect an event, SW should clear any stray attempts before
+signalling to the user that a touch event is expected. Clearing an
+event is done by writing the the status address, the value written
+does not matter.
+
+When an event has been detected, that is the sampled input from the
+sensor has gone from low to high, the STATUS_EVENT_BIT will be high
+(set). When SW reads a high bit, the SW should as soon as possible
+clear the event by writing to the status register. The value written
+does not matter.
+
+The FINGER_PRESENT bit is the sampled input from the sensor. The bit
+will be high as long as a finger is present on the sensor. When a
+finger is present the bit will be low.

hw/application_fpga/core/touch_sense/rtl/touch_sense.v

@@ -31,12 +31,14 @@ module touch_sense(
   //----------------------------------------------------------------
   // Internal constant and parameter definitions.
   //----------------------------------------------------------------
-  localparam ADDR_STATUS      = 8'h09;
-  localparam STATUS_EVENT_BIT = 0;
+  localparam ADDR_STATUS        = 8'h09;
+  localparam STATUS_EVENT_BIT   = 0;
+  localparam ADDR_PRESENT       = 8'h0a;
+  localparam FINGER_PRESENT_BIT = 0;
 
-  localparam CTRL_IDLE        = 2'h0;
-  localparam CTRL_EVENT       = 2'h1;
-  localparam CTRL_WAIT        = 2'h2;
+  localparam CTRL_IDLE          = 2'h0;
+  localparam CTRL_EVENT         = 2'h1;
+  localparam CTRL_WAIT          = 2'h2;
 
 
   //----------------------------------------------------------------
@@ -120,6 +122,10 @@ module touch_sense(
 	  if (address == ADDR_STATUS) begin
 	    tmp_read_data[STATUS_EVENT_BIT] = touch_event_reg;
 	  end
+
+	  if (address == ADDR_PRESENT) begin
+	    tmp_read_data[FINGER_PRESENT_BIT] = touch_event_sample1_reg;
+	  end
         end
       end
     end // api

hw/application_fpga/fw/tk1_mem.h

@@ -98,6 +98,8 @@
 #define TK1_MMIO_TOUCH_BASE 0xc4000000
 #define TK1_MMIO_TOUCH_STATUS 0xc4000024
 #define TK1_MMIO_TOUCH_STATUS_EVENT_BIT 0
+#define TK1_MMIO_TOUCH_PRESENT 0xc4000028
+#define TK1_MMIO_TOUCH_PRESENT_BIT 0
 
 // This only exists in QEMU, not real hardware
 #define TK1_MMIO_QEMU_BASE 0xfe000000