Add support for 16 bit port numbers (#9)

New interfaces are added instaed of modifying the old ones in order to keep compatibility. The most important change is the addition of the InstructionExecutorExtendedPorts property to the Z80Processor class.

Author: Konamiman

Docs/Configuration.md

@@ -21,3 +21,42 @@ _NOTE:_ Remember that plugging [custom dependencies](Dependencies.md) is an alte
 * **`SetPortWaitStates`** and **`GetPortWaitStates`** methods allow to configure the amount of extra T states that will be counted for timing purposes when a port is read or written during the execution of an instruction (not including the extra T state that is always added by the Z80 itself). The default value is zero for the entire ports space.
 
 * **`UserState`**: This is a convenience property that can be used by the client code to store just anything. The code of the processor class will never access this property for anything. The default value is _null_.
+
+* **`UseExtendedPortsSpace`**: Enables or disables the extended ports space (it's disabled by default), see below for details.
+
+
+### The extended ports space
+
+In a real Z80 processor the port access instructions (`IN`, `INI`, `INIR`, `IND`, `INDR`, `OUT`, `OUTI`, `OTIR`, `OUTD`, `OTDR`) work with 16 bit port numbers. These port numbers are composed as follows:
+
+* The lower half, whose value is set to pins A7-A0 of the address bus, is included in the instruction itself, either explicitly (as part of the instruction opcode) or implicitly (in register C).
+* The higher half, whose value is set to pins A15-A8 of the address bus, is taken from register A or B (when the instruction begins its execution) as follows:
+  * For the `IN A,(n)` and `OUT (n),A` instructions: register A.
+  * For the other instructions: register B.
+
+Z80.NET 1.0 didn't support 16 bit port numbers: register A/B was ignored and the actual port accessed was always a number in the range 0-255, as specified by the instruction opcode or as taken from register C.
+
+Z80.NET 1.1 implements a new boolean property, `UseExtendedPortsSpace`, that works as follows:
+
+* When it's `false` (default) the behavior is as in Z80.NET 1.0: port numbers are always 8 bit values.
+* When it's `true`, 16 bit port numbers are supported as specified above.
+
+For example, take the following snippet:
+
+```
+ld a,12h
+in a,(34h)
+```
+
+* When `UseExtendedPortsSpace` is `false` this will load A with the value of `PortsSpace[0x34]`.
+* When `UseExtendedPortsSpace` is `true` this will load A with the value of `PortsSpace[0x1234]`.
+
+Note that before setting `UseExtendedPortsSpace` to `true` you need to set `PortsSpace` to an instance of `IMemory` that reports a size of at least 65536, otherwise you'll get an exception; example:
+
+```C#
+var Z80 = new Z80Processor();
+Z80.PortsSpace = new PlainMemory(65536);
+Z80.UseExtendedPortsSpace = true;
+```
+
+You may want to take a look at [the relevant unit tests](../Main.Tests/Z80ProcessorTests_PortsAccess.cs) for more details on how port access works depending on the value of `UseExtendedPortsSpace`.

Main.Tests/Instructions Execution/IN A,(n) .Tests.cs

@@ -15,7 +15,7 @@ public void IN_A_n_reads_value_from_port()
             var oldValue = Fixture.Create<byte>();
 
             Registers.A = oldValue;
-            SetPortValue(portNumber, value);
+            SetPortValue(NumberUtils.CreateUshort(portNumber, oldValue), value);
 
             Execute(IN_A_n_opcode, null, portNumber);
 

Main.Tests/Instructions Execution/IN r,(C). .Tests.cs

@@ -28,15 +28,15 @@ public class IN_r_C : InstructionsExecutionTestsBase
         [TestCaseSource(nameof(IN_r_C_Source))]
         public void IN_r_C_reads_value_from_port(string reg, byte opcode)
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
             var value = Fixture.Create<byte>();
             var oldValue = Fixture.Create<byte>();
 
             if(reg != "C")
-                SetReg(reg, value);
-            Registers.A = oldValue;
+                SetReg(reg, oldValue);
 
-            Execute(opcode, portNumber, value);
+            Execute(opcode, portNumberLow, portNumberHigh, value);
 
             Assert.That(GetReg<byte>(reg), Is.EqualTo(value));
         }
@@ -46,18 +46,19 @@ public void IN_r_C_reads_value_from_port(string reg, byte opcode)
         [TestCaseSource(nameof(IN_F_C_Source))]
         public void IN_r_C_sets_SF_appropriately(string reg, byte opcode)
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
 
-            Execute(opcode, portNumber, 0xFE);
+            Execute(opcode, portNumberLow, portNumberHigh, 0xFE);
             Assert.That(Registers.SF.Value, Is.EqualTo(1));
 
-            Execute(opcode, portNumber, 0xFF);
+            Execute(opcode, portNumberLow, portNumberHigh, 0xFF);
             Assert.That(Registers.SF.Value, Is.EqualTo(1));
 
-            Execute(opcode, portNumber, 0);
+            Execute(opcode, portNumberLow, portNumberHigh, 0);
             Assert.That(Registers.SF.Value, Is.EqualTo(0));
 
-            Execute(opcode, portNumber, 1);
+            Execute(opcode, portNumberLow, portNumberHigh, 1);
             Assert.That(Registers.SF.Value, Is.EqualTo(0));
         }
 
@@ -66,15 +67,16 @@ public void IN_r_C_sets_SF_appropriately(string reg, byte opcode)
         [TestCaseSource(nameof(IN_F_C_Source))]
         public void IN_r_C_sets_ZF_appropriately(string reg, byte opcode)
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
 
-            Execute(opcode, portNumber, 0xFF);
+            Execute(opcode, portNumberLow, portNumberHigh, 0xFF);
             Assert.That(Registers.ZF.Value, Is.EqualTo(0));
 
-            Execute(opcode, portNumber, 0);
+            Execute(opcode, portNumberLow, portNumberHigh, 0);
             Assert.That(Registers.ZF.Value, Is.EqualTo(1));
 
-            Execute(opcode, portNumber, 1);
+            Execute(opcode, portNumberLow, portNumberHigh, 1);
             Assert.That(Registers.ZF.Value, Is.EqualTo(0));
         }
 
@@ -92,16 +94,17 @@ public void IN_r_C_resets_HF_NF(string reg, byte opcode)
         public void IN_r_C_does_not_change_CF(string reg, byte opcode)
         {
             var randomValues = Fixture.Create<byte[]>();
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
 
             foreach (var value in randomValues)
             {
                 Registers.CF = 0;
-                Execute(opcode, portNumber, value);
+                Execute(opcode, portNumberLow, portNumberHigh, value);
                 Assert.That(Registers.CF.Value, Is.EqualTo(0));
 
                 Registers.CF = 1;
-                Execute(opcode, portNumber, value);
+                Execute(opcode, portNumberLow, portNumberHigh, value);
                 Assert.That(Registers.CF.Value, Is.EqualTo(1));
             }
         }
@@ -112,11 +115,12 @@ public void IN_r_C_does_not_change_CF(string reg, byte opcode)
         public void IN_r_C_sets_PF_as_parity(string reg, byte opcode)
         {
             var randomValues = Fixture.Create<byte[]>();
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
 
             foreach (var value in randomValues)
             {
-                Execute(opcode, portNumber, value);
+                Execute(opcode, portNumberLow, portNumberHigh, value);
                 Assert.That(Registers.PF.Value, Is.EqualTo(Parity[value]));
             }
         }
@@ -126,17 +130,18 @@ public void IN_r_C_sets_PF_as_parity(string reg, byte opcode)
         [TestCaseSource(nameof(IN_F_C_Source))]
         public void IN_r_C_sets_bits_3_and_5_from_result(string reg, byte opcode)
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
             var value = ((byte)0).WithBit(3, 1).WithBit(5, 0);
-            Execute(opcode, portNumber, value);
+            Execute(opcode, portNumberLow, portNumberHigh, value);
             Assert.Multiple(() =>
             {
                 Assert.That(Registers.Flag3.Value, Is.EqualTo(1));
                 Assert.That(Registers.Flag5.Value, Is.EqualTo(0));
             });
 
             value = ((byte)0).WithBit(3, 0).WithBit(5, 1);
-            Execute(opcode, portNumber, value);
+            Execute(opcode, portNumberLow, portNumberHigh, value);
             Assert.Multiple(() =>
             {
                 Assert.That(Registers.Flag3.Value, Is.EqualTo(0));
@@ -149,16 +154,18 @@ public void IN_r_C_sets_bits_3_and_5_from_result(string reg, byte opcode)
         [TestCaseSource(nameof(IN_F_C_Source))]
         public void IN_r_C_returns_proper_T_states(string reg, byte opcode)
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
+            var portNumberHigh = Fixture.Create<byte>();
             var value = Fixture.Create<byte>();
-            var states = Execute(opcode, portNumber, value);
+            var states = Execute(opcode, portNumberLow, portNumberHigh, value);
             Assert.That(states, Is.EqualTo(12));
         }
 
-        private int Execute(byte opcode, byte portNumber, byte value)
+        private int Execute(byte opcode, byte portNumberLow, byte portNumberHigh, byte value)
         {
-            Registers.C = portNumber;
-            SetPortValue(portNumber, value);
+            Registers.C = portNumberLow;
+            Registers.B = portNumberHigh;
+            SetPortValue(NumberUtils.CreateUshort(portNumberLow, portNumberHigh), value);
             return Execute(opcode, 0xED);
         }
     }

Main.Tests/Instructions Execution/OUT (n),A .Tests.cs

@@ -8,18 +8,18 @@ public class OUT_A_n_tests : InstructionsExecutionTestsBase
         private const byte OUT_A_n_opcode = 0xD3;
 
         [Test]
-        public void OUT_A_n_reads_value_from_port()
+        public void OUT_A_n_writes_value_to_port()
         {
-            var portNumber = Fixture.Create<byte>();
+            var portNumberLow = Fixture.Create<byte>();
             var value = Fixture.Create<byte>();
             var oldValue = Fixture.Create<byte>();
 
             Registers.A = value;
-            SetPortValue(portNumber, oldValue);
+            SetPortValue(NumberUtils.CreateUshort(portNumberLow, value), oldValue);
 
-            Execute(OUT_A_n_opcode, null, portNumber);
+            Execute(OUT_A_n_opcode, null, portNumberLow);
 
-            Assert.That(GetPortValue(portNumber), Is.EqualTo(value));
+            Assert.That(GetPortValue(NumberUtils.CreateUshort(portNumberLow, value)), Is.EqualTo(value));
         }
 
         [Test]

Main.Tests/Instructions Execution/_InstructionsExecutionTestsBase.cs

@@ -20,6 +20,7 @@ public void Setup()
         {
             Sut = new Z80InstructionExecutor();
             Sut.ProcessorAgent = ProcessorAgent = new FakeProcessorAgent();
+            Sut.ProcessorAgentExtendedPorts = ProcessorAgent;
             Registers = ProcessorAgent.Registers;
             Sut.InstructionFetchFinished += (s, e) => { };
 
@@ -30,12 +31,12 @@ public void Setup()
 
         protected int nextFetchesAddress;
 
-        protected void SetPortValue(byte portNumber, byte value)
+        protected void SetPortValue(ushort portNumber, byte value)
         {
             ProcessorAgent.Ports[portNumber] = value;
         }
 
-        protected byte GetPortValue(byte portNumber)
+        protected byte GetPortValue(ushort portNumber)
         {
             return ProcessorAgent.Ports[portNumber];
         }
@@ -61,7 +62,8 @@ protected FakeInstructionExecutor NewFakeInstructionExecutor()
         {
 			var sut = new FakeInstructionExecutor();
             sut.ProcessorAgent = ProcessorAgent = new FakeProcessorAgent();
-		    Registers = ProcessorAgent.Registers;
+            sut.ProcessorAgentExtendedPorts = ProcessorAgent;
+            Registers = ProcessorAgent.Registers;
 			sut.InstructionFetchFinished += (s, e) => { };
             return sut;
         }
@@ -375,13 +377,13 @@ protected override int ExecuteUnsopported_ED_Instruction(byte secondOpcodeByte)
 		    }
         }
 
-        protected class FakeProcessorAgent : IZ80ProcessorAgent
+        protected class FakeProcessorAgent : IZ80ProcessorAgent, IZ80ProcessorAgentExtendedPorts
         {
             public FakeProcessorAgent()
             {
                 Registers = new Z80Registers();
                 Memory = new byte[65536];
-                Ports = new byte[256];
+                Ports = new byte[65536];
             }
 
             public byte[] Memory { get; set; }
@@ -433,6 +435,16 @@ public void Stop(bool isPause = false)
             {
                 throw new NotImplementedException();
             }
+
+            public byte ReadFromPort(byte portNumberLow, byte portNumberHigh)
+            {
+                return Ports[NumberUtils.CreateUshort(portNumberLow, portNumberHigh)];
+            }
+
+            public void WriteToPort(byte portNumberLow, byte portNumberHigh, byte value)
+            {
+                Ports[NumberUtils.CreateUshort(portNumberLow, portNumberHigh)] = value;
+            }
         }
 
         #endregion