Complete testbench and update README with API info

Signed-off-by: Joachim Strömbergson <joachim@assured.se>

hw/application_fpga/core/touch_sense/README.md

@@ -1,5 +1,27 @@
 # touch_sense
-Core that handles touch senor events and provides them via an API.
+
+Core that handles touch senor events and provides them SW via an API.
 
 ## Introduction
-This core implements a touch sensor handler. The core detects and holds events for SW to read. The user must lift the finger between touch events.
+
+This core implements a touch sensor handler. The core detects and
+holds events for SW to read. The touch sensor input is expected to be
+a change in level from low (0) to high (1). When an event is seen, the
+core will set a status bit that SW can read. SW must then clear the
+event by writing to the status register.
+
+The user is expected to lift the finger between multiple touch events.
+
+
+## API
+
+The API has a single address, and a single bit in that address:
+
+```
+	ADDR_STATUS: 0x09
+	STATUS_EVENT_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.

hw/application_fpga/core/touch_sense/tb/tb_touch_sense.v

@@ -18,16 +18,12 @@ module tb_touch_sense();
   //----------------------------------------------------------------
   // Internal constant and parameter definitions.
   //----------------------------------------------------------------
-  parameter DEBUG     = 0;
+  parameter DEBUG     = 1;
   parameter DUMP_WAIT = 0;
 
   parameter CLK_HALF_PERIOD = 1;
   parameter CLK_PERIOD = 2 * CLK_HALF_PERIOD;
 
-  localparam ADDR_NAME0        = 8'h00;
-  localparam ADDR_NAME1        = 8'h01;
-  localparam ADDR_VERSION      = 8'h02;
-
   localparam ADDR_STATUS       = 8'h09;
   localparam STATUS_READY_BIT  = 0;
 
@@ -174,7 +170,7 @@ module tb_touch_sense();
   //
   // Write the given word to the DUT using the DUT interface.
   //----------------------------------------------------------------
-  task write_word(input [11 : 0] address,
+  task write_word(input [7 : 0] address,
                   input [31 : 0] word);
     begin
       if (DEBUG)
@@ -200,7 +196,7 @@ module tb_touch_sense();
   // the word read will be available in the global variable
   // read_data.
   //----------------------------------------------------------------
-  task read_word(input [11 : 0]  address);
+  task read_word(input [7 : 0]  address);
     begin
       tb_address = address;
       tb_cs = 1;
@@ -233,7 +229,10 @@ module tb_touch_sense();
 
 
   //----------------------------------------------------------------
-  // test1()
+  // test1.
+  // Create a touch event check that it is accessible from the
+  // API. Clear the event from the API and check that it is
+  // really cleared.
   //----------------------------------------------------------------
   task test1;
     begin
@@ -242,10 +241,45 @@ module tb_touch_sense();
       $display("");
       $display("--- test1: started.");
 
+      // Set touch event to low:
+      tb_touch_event = 1'h0;
+
+      // Clear the event handler.
+      $display("--- test1: Clearing any stray event.");
+      write_word(8'h09, 32'h0);
+
+
+      // Check status.
+      #(CLK_PERIOD);
+      read_word(8'h09);
+
+      // Set touch event input to high.
+      $display("--- test1: Creating a touch event.");
+      tb_touch_event = 1'h1;
+
+      $display("--- test1: Waiting for the event to be caught.");
+      wait_ready();
+
+      $display("--- test1: Event has been seen.");
+
+      $display("--- test1: Dropping the event input.");
+      tb_touch_event = 1'h0;
+      #(CLK_PERIOD);
+      $display("--- test1: Clearing the event.");
+      write_word(8'h09, 32'h0);
+      #(CLK_PERIOD);
+
+      // Check that the event is now removed.
+      read_word(8'h09);
+      #(CLK_PERIOD);
+      $display("--- test1: Event has been cleared.");
+      read_word(8'h09);
+      #(CLK_PERIOD);
+
       $display("--- test1: completed.");
       $display("");
     end
-  endtask // tes1
+  endtask // test1
 
 
   //----------------------------------------------------------------
@@ -260,6 +294,7 @@ module tb_touch_sense();
 
       init_sim();
       reset_dut();
+
       test1();
 
       display_test_result();