From b65c44c4a8e86a4af2f2d96c26a1fe16753637ba Mon Sep 17 00:00:00 2001
From: Vi Grey <vi@vigrey.com>
Date: Sun, 24 Sep 2023 18:52:21 +0000
Subject: Add 2 new packets.  Remove 2 packets.

Changed
- Specify INPUT_CHUNK offset for Index Value of TRANSITION packet

Fixed
- EXPERIMENTAL packet drawing error and packet value length

Added
- PORT_LATCH_FILTER
- Port value to TRANSITION packet

Removed
- SNES_LATCH_FILTER and NES_LATCH_FILTER
---
 src/docs/draft-tasd-spec-0001.xml | 114 ++++++++++++++++++++------------------
 1 file changed, 60 insertions(+), 54 deletions(-)

(limited to 'src/docs')

diff --git a/src/docs/draft-tasd-spec-0001.xml b/src/docs/draft-tasd-spec-0001.xml
index d541237..e63af21 100644
--- a/src/docs/draft-tasd-spec-0001.xml
+++ b/src/docs/draft-tasd-spec-0001.xml
@@ -248,6 +248,7 @@
             <dt><tt>[00 14]</tt></dt> <dd>MOVIE_LICENSE</dd>
             <dt><tt>[00 15]</tt></dt> <dd>MOVIE_FILE</dd>
             <dt><tt>[00 F0]</tt></dt> <dd>PORT_CONTROLLER</dd>
+            <dt><tt>[00 F1]</tt></dt> <dd>PORT_OVERREAD</dd>
           </dl>
         </section>
         <section numbered="true" toc="default">
@@ -255,7 +256,6 @@
           <dl spacing="compact">
             <dt><tt>[01 01]</tt></dt> <dd>NES_LATCH_FILTER</dd>
             <dt><tt>[01 02]</tt></dt> <dd>NES_CLOCK_FILTER</dd>
-            <dt><tt>[01 03]</tt></dt> <dd>NES_OVERREAD</dd>
             <dt><tt>[01 04]</tt></dt> <dd>NES_GAME_GENIE_CODE</dd>
           </dl>
         </section>
@@ -263,7 +263,6 @@
           <name>SNES Specific Keys</name>
           <dl spacing="compact">
             <dt><tt>[02 02]</tt></dt> <dd>SNES_CLOCK_FILTER</dd>
-            <dt><tt>[02 03]</tt></dt> <dd>SNES_OVERREAD</dd>
             <dt><tt>[02 04]</tt></dt> <dd>SNES_GAME_GENIE_CODE</dd>
             <dt><tt>[02 05]</tt></dt> <dd>SNES_LATCH_TRAIN</dd>
           </dl>
@@ -342,6 +341,8 @@
             <dd>Specifies the TAS movie data.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type.  Discussed in (<xref target="movie_file"/>).</dd>
             <dt><tt>[00 F0]</tt> - PORT_CONTROLLER</dt>
             <dd>Specifies the controller type in specific console controller ports for the TAS when played on hardware.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form.  Discussed in (<xref target="port_controller"/>).</dd>
+            <dt><tt>[00 F1]</tt> - PORT_OVERREAD</dt>
+            <dd>Specifies whether a high or low signal <bcp14>SHOULD</bcp14> be sent through a specified controller port of the console if the console requests more input data from the replay device through that controller port than expected.  This packet type is <bcp14>OPTIONAL</bcp14>. Discussed in (<xref target="port_overread"/>).</dd>
           </dl>
         </section>
         <section numbered="true" toc="default">
@@ -351,8 +352,6 @@
             <dd>Specifies a latch filter time in microseconds for how long how long to wait after a latch signal until new latch signals <bcp14>SHOULD</bcp14> be accepted by the replay device.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form.  Discussed in (<xref target="nes_latch_filter"/>).</dd>
             <dt><tt>[01 02]</tt> - NES_CLOCK_FILTER</dt>
             <dd>Specifies a clock filter time in tenths of a microsecond (0.1 microseconds or 100 nanoseconds) for how long to wait after a clock pulse until new clock pulses <bcp14>SHOULD</bcp14> be accepted by the replay device.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form.  Discussed in (<xref target="nes_clock_filter"/>).</dd>
-            <dt><tt>[01 03]</tt> - NES_OVERREAD</dt>
-            <dd>Specifies whether a high or low signal <bcp14>SHOULD</bcp14> be sent to the NES console if the console clocks the replay device for more input buttons than are expected for the latch.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form. Discussed in (<xref target="nes_overread"/>).</dd>
             <dt><tt>[01 04]</tt> - NES_GAME_GENIE_CODE</dt>
             <dd>Specifies a Game Genie code for the TAS. This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>MAY</bcp14> contain more than 1 of this packet type.  Discussed in (<xref target="nes_game_genie_code"/>).</dd>
           </dl>
@@ -360,10 +359,10 @@
         <section numbered="true" toc="default">
           <name>SNES Specific Key Descriptions</name>
           <dl newline="true">
+            <dt><tt>[01 01]</tt> - SNES_LATCH_FILTER</dt>
+            <dd>Specifies a latch filter time in microseconds for how long how long to wait after a latch signal until new latch signals <bcp14>SHOULD</bcp14> be accepted by the replay device.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form.  Discussed in (<xref target="snes_latch_filter"/>).</dd>
             <dt><tt>[02 02]</tt> - SNES_CLOCK_FILTER</dt>
             <dd>Specifies a clock filter time in tenths of a microsecond (0.1 microseconds or 100 nanoseconds) for how long to wait after a clock pulse until new clock pulses <bcp14>SHOULD</bcp14> be accepted by the replay device.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form.  Discussed in (<xref target="snes_clock_filter"/>).</dd>
-            <dt><tt>[02 03]</tt> - SNES_OVERREAD</dt>
-            <dd>Specifies whether a high or low signal <bcp14>SHOULD</bcp14> be sent to the SNES console if the console clocks the replay device for more input buttons than are expected for the latch.  This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>SHOULD NOT</bcp14> contain more than 1 of this packet type in direct form. Discussed in (<xref target="snes_overread"/>).</dd>
             <dt><tt>[02 04]</tt> - SNES_GAME_GENIE_CODE</dt>
             <dd>Specifies a Game Genie code for the TAS. This packet type is <bcp14>OPTIONAL</bcp14> and a <strong>TASD</strong> file <bcp14>MAY</bcp14> contain more than 1 of this packet type.  Discussed in (<xref target="snes_game_genie_code"/>).</dd>
             <dt><tt>[02 05]</tt> - SNES_LATCH_TRAIN</dt>
@@ -790,7 +789,7 @@
       | Type (A) | Base (A) | Identifier (A) |
       +----------+----------+================+
 
-      Type (Binary Data):               [1 octet]
+      Type (Binary Data):                     [1 octet]
          [01] - CRC-8 Checksum
          [02] - CRC-16 Checksum
          [03] - CRC-32 Checksum
@@ -918,6 +917,25 @@
               <dd>Specifies the controller type connected to the <strong>Port</strong>.  <strong>(RESERVED)</strong> specifies that the controller type is not described in this document, but the byte values are reserved for a later version of the <strong>TASD</strong> file format protocol.  Input formats for specific controller types are described in (<xref target="controller_inputs"/>).</dd>
             </dl>
           </section>
+        	<section numbered="true" toc="default" anchor="port_overread">
+          	<name>PORT_OVERREAD Packet</name>
+          	<t>PORT_OVERREAD packets <bcp14>MUST</bcp14> be in the following format:</t>
+          	<artwork><![CDATA[
+          0          1
+      +----------+----------+
+      | Port (N) | High (B) |
+      +----------+----------+
+
+      Port (N)                                [1 octet]
+      High (Boolean)                          [1 octet]]]>
+        	  </artwork>
+        	  <dl newline="true">
+        	    <dt><strong>Port</strong></dt>
+        	    <dd>Controller port number (<strong>Port</strong> number <bcp14>MUST</bcp14> be <strong>1-indexed</strong>).</dd>
+        	    <dt><strong>High</strong></dt>
+        	    <dd>Boolean value that is <strong>TRUE</strong> if overread bits are set to high and <strong>FALSE</strong> if overread bits are set to low.</dd>
+        	  </dl>
+        	</section>
         </section>
         <section numbered="true" toc="default">
           <name>NES Specific Key Payload Formats</name>
@@ -953,22 +971,6 @@
               <dd>Clock filter length of time in tenths of a microsecond (units of 0.1 microseconds or 100 nanoseconds).</dd>
             </dl>
           </section>
-          <section numbered="true" toc="default" anchor="nes_overread">
-            <name>NES_OVERREAD Packet</name>
-            <t>NES_OVERREAD packets <bcp14>MUST</bcp14> be in the following format:</t>
-            <artwork><![CDATA[
-           0
-      +----------+
-      | High (B) |
-      +----------+
-
-      High (Boolean)                          [1 octet]]]>
-            </artwork>
-            <dl newline="true">
-              <dt><strong>High</strong></dt>
-              <dd>Boolean value that is <strong>TRUE</strong> if overread bits are set to high and <strong>FALSE</strong> if overread bits are set to low.</dd>
-            </dl>
-          </section>
           <section numbered="true" toc="default" anchor="nes_game_genie_code">
             <name>NES_GAME_GENIE_CODE Packet</name>
             <t>NES_GAME_GENIE_CODE packets <bcp14>MUST</bcp14> be in the following format:</t>
@@ -990,36 +992,36 @@
         </section>
         <section numbered="true" toc="default">
           <name>SNES Specific Key Payload Formats</name>
-          <section numbered="true" toc="default" anchor="snes_clock_filter">
-            <name>SNES_CLOCK_FILTER Packet</name>
-            <t>SNES_CLOCK_FILTER packets <bcp14>MUST</bcp14> be in the following format:</t>
+          <section numbered="true" toc="default" anchor="snes_latch_filter">
+            <name>SNES_LATCH_FILTER Packet</name>
+            <t>SNES_LATCH_FILTER packets <bcp14>MUST</bcp14> be in the following format:</t>
             <artwork><![CDATA[
-           0
-      +----------+
-      | Time (N) |
-      +----------+
+         0     1
+      +-----+-----+
+      | Time (N)  |
+      +-----+-----+
 
-      Time (Unsigned Integer)                 [1 octet]]]>
+      Time (Unsigned Integer)                 [2 octets]]]>
             </artwork>
             <dl newline="true">
               <dt><strong>Time</strong></dt>
-              <dd>Clock filter length of time in tenths of a microsecond (units of 0.1 microseconds or 100 nanoseconds).</dd>
+              <dd>Latch filter length of time in microseconds.</dd>
             </dl>
           </section>
-          <section numbered="true" toc="default" anchor="snes_overread">
-            <name>SNES_OVERREAD Packet</name>
-            <t>SNES_OVERREAD packets <bcp14>MUST</bcp14> be in the following format:</t>
+          <section numbered="true" toc="default" anchor="snes_clock_filter">
+            <name>SNES_CLOCK_FILTER Packet</name>
+            <t>SNES_CLOCK_FILTER packets <bcp14>MUST</bcp14> be in the following format:</t>
             <artwork><![CDATA[
            0
       +----------+
-      | High (B) |
+      | Time (N) |
       +----------+
 
-      High (Boolean)                          [1 octet]]]>
+      Time (Unsigned Integer)                 [1 octet]]]>
             </artwork>
             <dl newline="true">
-              <dt><strong>High</strong></dt>
-              <dd>Boolean value that is <strong>TRUE</strong> if overread bits are set to high and <strong>FALSE</strong> if overread bits are set to low.</dd>
+              <dt><strong>Time</strong></dt>
+              <dd>Clock filter length of time in tenths of a microsecond (units of 0.1 microseconds or 100 nanoseconds).</dd>
             </dl>
           </section>
           <section numbered="true" toc="default" anchor="snes_game_genie_code">
@@ -1145,14 +1147,14 @@
             <name>TRANSITION Packet</name>
             <t>TRANSITION packets <bcp14>MUST</bcp14> be in the following format:</t>
             <artwork><![CDATA[
-               0        1  2  3  4  5  6  7  8       9
-      +----------------+--+--+--+--+--+--+--+--+----------+
-      | Index Type (A) |       Index (N)       | Type (A) | ...
-      +----------------+--+--+--+--+--+--+--+--+----------+
-          10...
-      +============+
-      | Packet (A) |
-      +============+
+               0            1      2  3  4  5  6  7  8  9
+      +----------------+----------+--+--+--+--+--+--+--+--+
+      | Index Type (A) | Port (N) |       Index (N)       | ...
+      +----------------+----------+--+--+--+--+--+--+--+--+
+           10         11...
+      +----------+============+
+      | Type (A) | Packet (A) |
+      +----------+============+
 
       Index Type (Binary Data):               [1 octet]
          [01] - Frame
@@ -1160,20 +1162,22 @@
          [03] - Milliseconds
          [04] - Microseconds * 10
          [05] - INPUT_CHUNK Index
+      Port (Unsigned Integer)                 [1 octet]
       Index (Unsigned Integer)                [8 octets]
       Type (Binary Data):                     [1 octet]
          [01] - Soft Reset
          [02] - Power Reset
          [03] - Restart TASD File
          [FF] - Packet Derived
-      Inner Packet (Binary Data)              [PLEN - 10 octets]]]>
+      Inner Packet (Binary Data)              [PLEN - 11 octets]]]>
             </artwork>
             <dl newline="true">
               <dt><strong>Input Type</strong></dt>
               <dd>Determines specific timing type for start of transition.</dd>
-
+              <dt><strong>Port</strong></dt>
+							<dd>Controller port number of input index.  If <strong>Index Type</strong> is <tt>[05]</tt>, <strong>Port</strong> <bcp14>MUST</bcp14> be <strong>1-indexed</strong> Port number, otherwise <strong>Port</strong> <bcp14>MAY</bcp14> be any value.</dd>
               <dt><strong>Index</strong></dt>
-              <dd>Time or offset value to start transition.</dd>
+							<dd>Time or offset value to start transition.  If <strong>Index Type</strong> is <tt>[05]</tt>, <strong>Index</strong> <bcp14>MUST</bcp14> be the byte offset of <strong>INPUT_CHUNK</strong> data from <strong>INPUT_CHUNK</strong> packets for the controller port specified by <strong>Port</strong>.</dd>
               <dt><strong>Type</strong></dt>
               <dd>Type of transition.  If <strong>Type</strong> is <tt>[FF]</tt>, the transition action will be interpreting a <strong>TASD</strong> packet.</dd>
               <dt><strong>Inner Packet</strong></dt>
@@ -1255,12 +1259,12 @@
             <name>EXPERIMENTAL Packet</name>
             <t>EXPERIMENTAL packets <bcp14>MUST</bcp14> be in the following format:</t>
             <artwork><![CDATA[
-              0...
-      +==================+
+               0
+      +------------------+
       | Experimental (B) |
-      +==================+
+      +------------------+
 
-      Experimental (Boolean)                  [PLEN octet]]]>
+      Experimental (Boolean)                  [1 octet]]]>
             </artwork>
             <dl newline="true">
               <dt><strong>Experimental</strong></dt>
@@ -1914,6 +1918,8 @@
     </section>
     <!-- Change Log
     
+draft 11 - 2023-09-24   VG   Made OVERREAD packets generic and added Port to it, now is PORT_OVERREAD.  Fixed packet drawing error in EXPERIMENTAL.  Added SNES_LATCH_FILTER.  Added Port to TRANSITION packet.  Specify meaning of INPUT_CHUNK offset for Index value of TRANSITION packet.
+
 draft 10 - 2023-09-18   VG   Specify that PEXP MUST be greater than 0
 
 draft 09 - 2023-09-17   Bigbass Added "Structure" section to better define the overall structure of a TASD file
-- 
cgit v1.2.3