zemu 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6f562e6869c6bcb8df2f0635bf7bc3f70d9668ab91f6d0806e6d1f0c767ec78
-  data.tar.gz: a83bf92a0244875db8b48d29cdd11eb74ee9ab94c1eb24c6b2255b8d3c81bcee
+  metadata.gz: b90e15af47b7ba86466e516ad1d1695c391095e43349536679433d4ac056aa7c
+  data.tar.gz: 1d2b05874a9b666c28c467426017ff12fdd1b25fafaadb71d8fcc44e33c89879
 SHA512:
-  metadata.gz: 9054649380e73ae6d96d2307c85cc2029d529ef6a0de7f4ebf17d05ac058ed66102b2efccb5a946cc0d828a4932f7121777212e2d8376571adb709aefa08c681
-  data.tar.gz: 4900928e8fe5f1ba241f3a99f5a17adbfd0b76c9caa08030b4278f8fec9b92ddae61c05326dede2d80ad60917090f4266a6af6b9d9c593178647a583460b57a2
+  metadata.gz: 5cb969fc0731adb33864a27eb80314afd926bee8c8a59e3b01164cd0794c764522c3e3171a86d5fccd2babd9273c1067913d8641d8b23e7f41f796670fc0b794
+  data.tar.gz: b2a7c1edf04f6a47b0a20ec05e00cd3861d028e81e34d460f98c8006d0f50d792f896dfc7d6d59c1c87b5612f6e72c069025105a4a1a71ab22fa8a1917b64f77

data/lib/zemu/config.rb

@@ -224,7 +224,7 @@ module Zemu
             # Valid parameters for a SerialPort, along with those
             # defined in [Zemu::Config::IOPort].
             def params
-                super + %w(in_port out_port)
+                super + %w(in_port out_port ready_port)
             end
         end
 

data/lib/zemu/instance.rb

@@ -93,12 +93,14 @@ module Zemu
         # Gets the given number of characters from the emulated machine's send buffer.
         #
         # Note: If count is greater than the number of characters currently in the buffer,
-        # the returned string may have invalid characters appended to the end.
+        # the returned string will be shorter than the given count.
         def serial_gets(count=nil)
             return_string = ""
 
-            if count.nil?
-                count = @wrapper.zemu_io_serial_buffer_size()
+            actual_count = @wrapper.zemu_io_serial_buffer_size()
+
+            if count.nil? || actual_count < count
+                count = actual_count
             end
 
             count.to_i.times do
@@ -111,8 +113,11 @@ module Zemu
         # Continue running this instance until either:
         # * A HALT instruction is executed
         # * A breakpoint is hit
-        def continue
-            @wrapper.zemu_debug_continue(@instance)
+        # * The number of cycles given has been executed
+        #
+        # Returns the number of cycles executed.
+        def continue(run_cycles=-1)
+            return @wrapper.zemu_debug_continue(@instance, run_cycles)
         end
 
         # Set a breakpoint of the given type at the given address.
@@ -156,7 +161,7 @@ module Zemu
 
             wrapper.attach_function :zemu_reset, [:pointer], :void
 
-            wrapper.attach_function :zemu_debug_continue, [:pointer], :void
+            wrapper.attach_function :zemu_debug_continue, [:pointer, :int64], :uint64
 
             wrapper.attach_function :zemu_debug_halted, [], :bool
             wrapper.attach_function :zemu_debug_break, [], :bool

data/lib/zemu/interactive.rb

@@ -0,0 +1,188 @@
+module Zemu
+    # An interactive instance of a Zemu emulator.
+    # Wraps a Zemu::Instance to allow for user input and debugging.
+    class InteractiveInstance
+        # Constructor.
+        #
+        # Create a new interactive wrapper for the given instance.
+        def initialize(instance)
+            @instance = instance
+
+            @master, @slave = PTY.open
+            log "Opened PTY at #{@slave.path}"
+        end
+
+        # Logs a message to the user output.
+        def log(message)
+            STDOUT.puts "    " + message
+        end
+
+        # Close the interactive wrapper
+        def close
+            @master.close
+            @slave.close
+            @instance.quit
+        end
+
+        # Run the interactive emulator until the user exits.
+        def run
+            quit = false
+
+            until quit
+                print "ZEMU> "
+                # Get a command from the user.
+                cmd = STDIN.gets.split
+
+                if cmd[0] == "quit"
+                    quit = true
+
+                elsif cmd[0] == "continue"
+                    if cmd[1].nil?
+                        continue
+                    else
+                        continue(cmd[1].to_i)
+                    end
+
+                elsif cmd[0] == "step"
+                    continue(1)
+
+                elsif cmd[0] == "registers"
+                    registers
+
+                elsif cmd[0] == "break"
+                    add_breakpoint(cmd[1])
+
+                elsif cmd[0] == "memory"
+                    if cmd[2].nil?
+                        memory(cmd[1])
+                    else
+                        memory(cmd[1], cmd[2])
+                    end
+
+                elsif cmd[0] == "help"
+                    log "Available commands:"
+                    log "    continue [<n>]     - Continue execution for <n> cycles"
+                    log "    step               - Step over a single instruction"
+                    log "    registers          - View register contents"
+                    log "    memory <a> [<n>]   - View <n> bytes of memory, starting at address <a>."
+                    log "                         <n> defaults to 1 if omitted."
+                    log "    break  <a>         - Set a breakpoint at the given address <a>."
+                    log "    quit               - End this emulator instance."
+
+                else
+                    log "Invalid command. Type 'help' for available commands."
+                    
+                end
+            end
+
+            close
+        end
+
+        # Outputs a table giving the current values of the instance's registers.
+        def registers
+            log "A:  #{r("A")} F: #{r("F")}"
+            log "B:  #{r("B")} C: #{r("C")}"
+            log "D:  #{r("D")} E: #{r("E")}"
+            log "H:  #{r("H")} L: #{r("L")}"
+            log ""
+            log "IX: #{r16("IX")}"
+            log "IY: #{r16("IY")}"
+            log "SP: #{r16("SP")}"
+            log "PC: #{r16("PC")}"
+        end
+
+        # Returns a particular 8-bit register value.
+        def r(reg)
+            return "0x%02x" % @instance.registers[reg]
+        end
+
+        # Returns a particular 16-bit register value.
+        def r16(reg)
+            return "0x%04x" % @instance.registers[reg]
+        end
+
+        # Continue for *up to* the given number of cycles.
+        # Fewer cycles may be executed, depending on the behaviour of the processor.
+        def continue(cycles=-1)
+            if cycles == 0
+                log "Invalid value: #{cycles}"
+                return
+            end
+
+            # Continue executing instruction-by-instruction.
+            # Process IO in-between.
+            cycles_left = cycles
+            actual_cycles = 0
+
+            while ((cycles == -1) || (cycles_left > 0))
+                old_pc = r16("PC")
+
+                process_serial
+                cycles_done = @instance.continue(1)
+                cycles_left -= cycles_done
+                actual_cycles += cycles_done
+
+                # Have we hit a breakpoint or HALT instruction?
+                if @instance.break?
+                    log "Hit breakpoint at #{r16("PC")}."
+                    break
+                elsif @instance.halted?
+                    log "Executed HALT instruction at #{old_pc}."
+                    break
+                end
+            end
+
+            log "Executed for #{actual_cycles} cycles."
+        end
+
+        # Add a breakpoint at the address given by the string.
+        def add_breakpoint(addr_str)
+            @instance.break(addr_str.to_i(16), :program)
+        end
+
+        # Dump an amount of memory.
+        def memory(address, size="1")
+            if address.nil?
+                log "Expected an address, got #{address}."
+                return
+            end
+
+            if (address.to_i(16) < 1 || address.to_i(16) > 0xffff)
+                log "Invalid address: 0x%04x" % address.to_i(16)
+                return
+            end
+            
+            (address.to_i(16)...address.to_i(16) + size.to_i(16)).each do |a|
+                m = @instance.memory(a)
+                if (m < 32)
+                    log "%04x: %02x    ." % [a, m]
+                else
+                    log ("%04x: %02x    " % [a, m]) + m.chr("UTF-8")
+                end
+            end
+        end
+
+        # Process serial input/output via the TTY.
+        def process_serial
+            # Read/write serial.
+            # Get the strings to be input/output.
+            input = ""
+            ready = IO.select([@master], [], [], 0)
+            unless ready.nil? || ready.empty?
+                input = @master.read(1)
+            end
+
+            output = @instance.serial_gets(1)
+
+            unless input.empty?
+                @instance.serial_puts input
+                log "Serial in: #{input}"
+            end
+
+            unless output.empty?
+                @master.write output
+                log "Serial out: #{output}"
+            end
+        end
+    end
+end

data/lib/zemu.rb

@@ -1,7 +1,10 @@
 require 'erb'
 
+require 'pty'
+
 require_relative 'zemu/config'
 require_relative 'zemu/instance'
+require_relative 'zemu/interactive'
 
 # Zemu is a module providing an interface to build and interact with
 # configurable Z80 emulators.
@@ -66,6 +69,16 @@ module Zemu
         return Instance.new(configuration)
     end
 
+    # Starts an interactive instance of an emulator, according to the given configuration.
+    #
+    # @param [Zemu::Config] configuration The configuration for which an emulator will be generated.
+    def Zemu::start_interactive(configuration)
+        instance = start(configuration)
+
+        interactive = InteractiveInstance.new(instance)
+        interactive.run
+    end
+
     # Builds a library according to the given configuration.
     #
     # @param [Zemu::Config] configuration The configuration for which an emulator will be generated.

data/src/debug.c

@@ -8,7 +8,7 @@ RunState zemu_debug_state = UNDEFINED;
 zuint16 breakpoints[ZEMU_DEBUG_MAX_BREAKPOINTS];
 unsigned int breakpoint_count = 0;
 
-zusize zemu_debug_continue(Z80 * instance)
+zusize zemu_debug_continue(Z80 * instance, zinteger run_cycles)
 {
     /* Return if we've halted. */
     if (zemu_debug_state == HALTED) return 0;
@@ -17,7 +17,11 @@ zusize zemu_debug_continue(Z80 * instance)
 
     zemu_debug_state = RUNNING;
 
-    while (zemu_debug_state == RUNNING)
+    /* Run as long as:
+     * We don't hit a breakpoint
+     * We haven't run for more than the number of cycles given
+     */
+    while (zemu_debug_state == RUNNING && (run_cycles < 0 || cycles < run_cycles))
     {
         cycles += zemu_debug_step(instance);
 

data/src/debug.h

@@ -17,7 +17,7 @@ typedef enum RunState
     UNDEFINED
 } RunState;
 
-zusize zemu_debug_continue(Z80 * instance);
+zusize zemu_debug_continue(Z80 * instance, zinteger run_cycles);
 
 zusize zemu_debug_step(Z80 * instance);
 

data/src/io.c.erb

@@ -92,6 +92,18 @@ zuint8 zemu_io_in(void * context, zuint16 port)
     {
         return zemu_io_serial_slave_gets();
     }
+
+    else if (port == <%= device.ready_port %>)
+    {
+        if (io_serial_buffer_master.head == io_serial_buffer_master.tail)
+        {
+            return 0;
+        }
+        else
+        {
+            return 1;
+        }
+    }
 <% end %>
 <% end %>
     return 0;

metadata

@@ -1,16 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: zemu
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Jay Valentine
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-31 00:00:00.000000000 Z
+date: 2020-02-18 00:00:00.000000000 Z
 dependencies: []
-description: A configurable Z80 emulator gem
+description: |2
+      Zemu is a gem which allows the user to configure a Z80-based system
+      and then launch emulation instances of that system.
+      These instances can be interacted with programmatically, allowing the
+      user to inspect the contents of registers and memory, step, add breakpoints,
+      and more.
+
+      The gem requires the user to install a compatible C compiler.
+      Currently the only compatible compiler is clang.
+
+      Please report any issues on the GitHub page for the gem.
+      This is accessible under "Homepage".
 email: jayv136@gmail.com
 executables: []
 extensions: []
@@ -19,6 +30,7 @@ files:
 - lib/zemu.rb
 - lib/zemu/config.rb
 - lib/zemu/instance.rb
+- lib/zemu/interactive.rb
 - src/debug.c
 - src/debug.h
 - src/external/Z/API/Z/ABIs/generic/allocator.h
@@ -325,5 +337,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: zemu
+summary: A configurable Z80 emulator.
 test_files: []