zemu 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98e90e196dcbb84331f8dab176c2b83610180e7ddd11df63f481328cab4b7d7a
+  data.tar.gz: c3cb5cde5230d2dbe34d228a170fa5cd35a6607614c215ea5c01792c1634ee08
+SHA512:
+  metadata.gz: 7359557085c2f32b9222c7836c0af65a1104e158f8f9c58d118a5dabbd50fdcb2cfe793957b41cded14af45566a2ddaad4d3148ee736da922e1347bde1bf0091
+  data.tar.gz: d20ce84cc9c41e11203b08e44865b6addf53d63846004f4aa575eb54f58b69200c454c18713569e94220dd6ea49a3dea84634870bfef5a32f58a81f7a04daf49

data/lib/zemu/config.rb

@@ -0,0 +1,312 @@
+module Zemu
+    # Abstract configuration object.
+    # All configuration objects should inherit from this.
+    class ConfigObject
+        # Defines the parameters of this configuration object.
+        def params
+            raise NotImplementedError, "params must be overridden by inheriting class."
+        end
+
+        protected :params
+
+        # Defines the initial values of parameters, if any.
+        def params_init
+            return {}
+        end
+
+        protected :params_init
+
+        def initialize(&block)
+            if self.class == Zemu::ConfigObject
+                raise NotImplementedError, "Cannot construct an instance of the abstract class Zemu::ConfigObject."
+            end
+
+            @initialized = false
+
+            # Initialize each parameter to nil
+            params.each do |p|
+                if params_init[p].nil?
+                    instance_variable_set("@#{p}", nil)
+                else
+                    instance_variable_set("@#{p}", params_init[p])
+                end
+            end
+
+            # Instance eval the block.
+            instance_eval(&block)
+
+            # Raise a ConfigError if any of the parameters are unset.
+            params.each do |p|
+                if instance_variable_get("@#{p}").nil?
+                    raise ConfigError, "The #{p} parameter of a #{self.class.name} configuration object must be set."
+                end
+            end
+
+            @initialized = true
+        end
+
+        # This allows some metaprogramming magic to allow the user to set instance variables
+        # (config parameters) while initializing the configuration object, but ensures
+        # that these parameters are readonly once the object is initialized.
+        def method_missing(m, *args, &block)
+            params.each do |v|
+                # We don't allow the setting of instance variables if the object
+                # has been initialized.
+                if m == "#{v}".to_sym
+                    if args.size == 1 && !@initialized
+                        instance_variable_set("@#{v}", args[0])
+                        return
+                    elsif args.size == 0
+                        return instance_variable_get("@#{v}")
+                    end
+                end
+            end
+            
+            # Otherwise just call super's method_missing
+            super
+        end
+    end
+
+    # Configuration object.
+    #
+    # An object which represents the configuration of a Zemu emulator.
+    #
+    # @param [String] name The name of the configuration.
+    # @param [String] compiler The path to the compiler to be used for compiling the emulator executable.
+    #
+    class Config < ConfigObject
+        # Memory object.
+        #
+        # This is an abstract class from which all other memory objects inherit.
+        class Memory < ConfigObject
+            # Constructor.
+            #
+            # Do not use, as this is an abstract class. Use one of the subclasses instead.
+            def initialize
+                if self.class == Zemu::Config::Memory
+                    raise NotImplementedError, "Cannot construct an instance of the abstract class Zemu::Config::Memory."
+                end
+
+                @contents = []
+
+                super
+
+                # Pad contents with 0x00 bytes.
+                (@size - @contents.size).times do
+                    @contents << 0x00
+                end
+            end
+
+            # Gets or sets an array of bytes representing the initial state
+            # of this memory block.
+            def contents(*args)
+                if args.size.zero?
+                    return @contents
+                else
+                    @contents = args[0]
+                end
+            end
+
+            # @return [Boolean] true if this memory section is readonly, false otherwise.
+            def readonly?
+                return false
+            end
+
+            # Valid parameters for this object.
+            # Should be extended by subclasses but NOT REPLACED.
+            def params
+                return %w(name address size)
+            end
+
+            # Reads the contents of a file in binary format and
+            # returns them as an array.
+            def from_binary(file)
+                return File.open(file, "rb") do |f|
+                    bin = []
+
+                    f.each_byte { |b| bin << b }
+
+                    bin
+                end
+            end
+        end
+
+        # Read-Only Memory object
+        #
+        # Represents a block of memory which is read-only.
+        class ROM < Memory
+            # Constructor.
+            #
+            # Takes a block in which the parameters of the memory block
+            # can be initialized.
+            #
+            # All parameters can be set within this block.
+            # They become readonly as soon as the block completes.
+            #
+            # @example
+            #   
+            #   Zemu::Config::ROM.new do
+            #       address 0x8000
+            #       size 256
+            #   end
+            #
+            #
+            def initialize
+                super
+            end
+
+            def readonly?
+                return true
+            end
+        end
+
+        # Random-access Memory object
+        #
+        # Represents a block of memory which can be read and written.
+        class RAM < Memory
+        end
+
+        # Input/Output Port object
+        #
+        # Represents an input/output device assigned to one or more ports.
+        class IOPort < ConfigObject
+            attr_reader :io_type
+
+            # Constructor.
+            #
+            # Do not use, as this is an abstract class. Use one of the subclasses instead.
+            def initialize
+                if self.class == Zemu::Config::IOPort
+                    raise NotImplementedError, "Cannot construct an instance of the abstract class Zemu::Config::IOPort."
+                end
+
+                @ports = []
+
+                super
+            end
+
+            # Valid parameters for this object.
+            # Should be extended by subclasses but NOT REPLACED.
+            def params
+                %w(name)
+            end
+        end
+        
+        # Serial Input/Output object
+        #
+        # Represents a serial connection between the emulated CPU
+        # and the host machine, with input and output mapped to Z80 I/O
+        # ports.
+        class SerialPort < IOPort
+            # Constructor.
+            #
+            # Takes a block in which the parameters of the serial port
+            # can be initialized.
+            #
+            # All parameters can be set within this block.
+            # They become readonly as soon as the block completes.
+            #
+            # @example
+            #   
+            #   Zemu::Config::SerialPort.new do
+            #       name "serial"
+            #       in_port 0x00
+            #       out_port 0x01
+            #   end
+            #
+            #
+            def initialize
+                super
+            
+                @io_type = :serial
+            end
+
+            # Valid parameters for a SerialPort, along with those
+            # defined in [Zemu::Config::IOPort].
+            def params
+                super + %w(in_port out_port)
+            end
+        end
+
+        # Gets a binding for this object.
+        def get_binding
+            return binding
+        end
+
+        # The memory sections of this configuration object.
+        attr_reader :memory
+
+        # The IO devices of this configuration object.
+        attr_reader :io
+
+        # Parameters accessible by this configuration object.
+        def params
+            return %w(name compiler output_directory)
+        end
+
+        # Initial value for parameters of this configuration object.
+        def params_init
+            return {
+                "compiler" => "clang",
+                "output_directory" => "bin"
+            }
+        end
+
+        # Constructor.
+        #
+        # Takes a block in which parameters of the configuration
+        # can be initialized.
+        #
+        # All parameters can be set within this block.
+        # They become readonly as soon as the block completes.
+        #
+        # @example
+        #
+        #   Zemu::Config.new do
+        #       name "my_config"
+        #
+        #       add_memory Zemu::Config::ROM.new do
+        #           name "rom"
+        #           address 0x0000
+        #           size 0x1000
+        #       end
+        #   end
+        #
+        # @raise [Zemu::ConfigError] Raised if the +name+ parameter is not set, or contains whitespace.
+        def initialize
+            @memory = []
+            @io = []
+
+            super
+
+            if @name.empty?
+                raise ConfigError, "The name parameter of a Zemu::Config configuration object cannot be empty."
+            end
+
+            if /\s/ =~ @name
+                raise ConfigError, "The name parameter of a Zemu::Config configuration object cannot contain whitespace."
+            end
+        end
+
+        # Adds a new memory section to this configuration.
+        #
+        # @param [Zemu::Config::Memory] mem The memory object to add.
+        def add_memory(mem)
+            @memory << mem
+        end
+
+        # Adds a new IO device to this configuration.
+        #
+        # @param [Zemu::Config::IOPort] io The IO device to add.
+        def add_io(io)
+            @io << io
+        end
+    end
+
+    # Error raised when a configuration is initialized incorrectly.
+    class ConfigError < StandardError
+        def initialize(msg="The configuration is invalid.")
+            super
+        end
+    end
+end

data/lib/zemu/instance.rb

@@ -0,0 +1,179 @@
+require 'ffi'
+require 'ostruct'
+
+module Zemu
+    # Represents an instance of a Zemu emulator.
+    #
+    # Provides methods by which the state of the emulator can be observed
+    # and the execution of the program controlled.
+    class Instance
+        # Mapping of register names to the ID numbers used to identify them
+        # by the debug functionality of the built library.
+        REGISTERS = {
+            # Special purpose registers
+            "PC" => 0,
+            "SP" => 1,
+            "IY" => 2,
+            "IX" => 3,
+
+            # Main register set
+            "A" => 4,
+            "F" => 5,
+            "B" => 6,
+            "C" => 7,
+            "D" => 8,
+            "E" => 9,
+            "H" => 10,
+            "L" => 11,
+
+            # Alternate register set
+            "A'" => 12,
+            "F'" => 13,
+            "B'" => 14,
+            "C'" => 15,
+            "D'" => 16,
+            "E'" => 17,
+            "H'" => 18,
+            "L'" => 19
+        }
+
+        def initialize(configuration)
+            @wrapper = make_wrapper(configuration)
+
+            @serial = []
+
+            @instance = @wrapper.zemu_init
+            @wrapper.zemu_power_on(@instance)
+            @wrapper.zemu_reset(@instance)
+        end
+
+        # Returns a hash containing current values of the emulated
+        # machine's registers. All names are as those given in the Z80
+        # reference manual.
+        #
+        # 16-bit general-purpose registers must be accessed by their 8-bit
+        # component registers.
+        def registers
+            r = {}
+
+            REGISTERS.each do |reg, num|
+                r[reg] = @wrapper.zemu_debug_register(@instance, num)
+            end
+            
+            return r
+        end
+
+        # Access the value in memory at a given address.
+        #
+        # @param address The address in memory to be accessed.
+        #
+        # Returns 0 if the memory address is not mapped, otherwise
+        # returns the value in the given memory location.
+        def memory(address)
+            return @wrapper.zemu_debug_get_memory(address)
+        end
+
+        # Write a string to the serial line of the emulated CPU.
+        #
+        # @param string The string to be sent.
+        #
+        # Sends each character in the string to the receive buffer of the
+        # emulated machine.
+        def serial_puts(string)
+            string.each_char do |c|
+                @wrapper.zemu_io_serial_master_puts(c.ord)
+            end
+        end
+
+        # Get a number of characters from the serial line of the emulated CPU.
+        #
+        # @param count The number of characters to get, or nil if all characters in the buffer
+        #              should be retrieved.
+        #
+        # 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.
+        def serial_gets(count=nil)
+            return_string = ""
+
+            if count.nil?
+                count = @wrapper.zemu_io_serial_buffer_size()
+            end
+
+            count.to_i.times do
+                return_string += @wrapper.zemu_io_serial_master_gets().chr
+            end
+
+            return return_string
+        end
+
+        # Continue running this instance until either:
+        # * A HALT instruction is executed
+        # * A breakpoint is hit
+        def continue
+            @wrapper.zemu_debug_continue(@instance)
+        end
+
+        # Set a breakpoint of the given type at the given address.
+        #
+        # @param address The address of the breakpoint
+        # @param type The type of breakpoint:
+        #   * :program => Break when the program counter hits the address given. 
+        def break(address, type)
+            @wrapper.zemu_debug_set_breakpoint(address)
+        end
+
+        # Returns true if the CPU has halted, false otherwise.
+        def halted?
+            return @wrapper.zemu_debug_halted
+        end
+
+        # Returns true if a breakpoint has been hit, false otherwise.
+        def break?
+            return @wrapper.zemu_debug_break
+        end
+
+        # Powers off the emulated CPU and destroys this instance.
+        def quit
+            @wrapper.zemu_power_off(@instance)
+            @wrapper.zemu_free(@instance)
+        end
+
+        # Creates a wrapper around the Zemu module built with the given configuration.
+        def make_wrapper(configuration)
+            wrapper = Module.new
+
+            wrapper.extend FFI::Library
+
+            wrapper.ffi_lib [File.join(configuration.output_directory, "#{configuration.name}.so")]
+
+            wrapper.attach_function :zemu_init, [], :pointer
+            wrapper.attach_function :zemu_free, [:pointer], :void
+
+            wrapper.attach_function :zemu_power_on, [:pointer], :void
+            wrapper.attach_function :zemu_power_off, [:pointer], :void
+
+            wrapper.attach_function :zemu_reset, [:pointer], :void
+
+            wrapper.attach_function :zemu_debug_continue, [:pointer], :void
+
+            wrapper.attach_function :zemu_debug_halted, [], :bool
+            wrapper.attach_function :zemu_debug_break, [], :bool
+
+            wrapper.attach_function :zemu_debug_set_breakpoint, [:uint16], :void
+
+            wrapper.attach_function :zemu_debug_register, [:pointer, :uint16], :uint16
+
+            wrapper.attach_function :zemu_debug_get_memory, [:uint16], :uint8
+
+            wrapper.attach_function :zemu_io_serial_master_puts, [:uint8], :void
+            wrapper.attach_function :zemu_io_serial_master_gets, [], :uint8
+            wrapper.attach_function :zemu_io_serial_buffer_size, [], :uint64
+
+            return wrapper
+        end
+
+        private :make_wrapper
+    end
+end

data/lib/zemu.rb

@@ -0,0 +1,172 @@
+require 'erb'
+
+require_relative 'zemu/config'
+require_relative 'zemu/instance'
+
+# Zemu
+#
+# Zemu is a module providing an interface to build and interact with
+# configurable Z80 emulators.
+#
+# Configurations can be defined in a declarative syntax, from which
+# an emulator executable can be compiled. This executable can then be run
+# from within Zemu and controlled programmatically.
+#
+# Please note: The example below does not currently work, as not all features
+# have been implemented.
+#
+# @example
+#
+#   require 'zemu'
+#
+#   # A simple configuration with a ROM block
+#   # and a RAM block.
+#   conf = Zemu::Config.new do
+#       name "zemu_emulator"
+#
+#       add_memory Zemu::Config::ROM.new do
+#           name "rom"
+#           address 0x0000
+#           size 0x4000
+#
+#           contents from_binary("app.bin")
+#       end
+#
+#       add_memory Zemu::Config::RAM.new do
+#           name "ram"
+#           address 0x8000
+#           size 0x1000
+#       end
+#   end
+#
+#   # Start a new instance with this configuration.
+#   instance = Zemu.start(conf)
+#
+#   # Program breakpoint.
+#   # Will trigger if the emulator is about to execute an
+#   # instruction at 0x102.
+#   instance.break 0x102, :program
+#
+#   # Continue. Emulator will run until HALT or until
+#   # the breakpoint (set above) is hit.
+#   instance.continue
+#
+#   # Display the value of the A register (accumulator)
+#   # at the breakpoint.
+#   puts instance.register["A"]
+#
+#   # Close the instance.
+#   instance.quit
+#
+module Zemu
+    # Location of C source for the emulator.
+    SRC = File.join(__dir__, "..", "src")
+
+    # Build and start an emulator according to the given configuration.
+    #
+    # @param [Zemu::Config] configuration The configuration for which an emulator will be generated.
+    def Zemu::start(configuration)
+        build(configuration)
+
+        return Instance.new(configuration)
+    end
+
+    # Builds a library according to the given configuration.
+    #
+    # @param [Zemu::Config] configuration The configuration for which an emulator will be generated.
+    #
+    # @returns true if the build is a success, false (build failed) or nil (compiler not found) otherwise.
+    def Zemu::build(configuration)
+        # Create the output directory unless it already exists.
+        unless Dir.exist? configuration.output_directory
+            Dir.mkdir configuration.output_directory
+        end
+        
+        # Generate the autogenerated source files.
+        generate(configuration)
+
+        output = File.join(configuration.output_directory, "#{configuration.name}.so")
+
+        autogen = File.join(configuration.output_directory, "autogen_#{configuration.name}")
+
+        compiler = configuration.compiler
+
+        inputs = [
+            "main.c",                       # main library functionality
+            "debug.c",                      # debug functionality
+            "interrupt.c",                  # interrupt functionality
+            "external/z80/sources/Z80.c"    # z80 core library
+        ]
+
+        inputs_str = inputs.map { |i| File.join(SRC, i) }.join(" ")
+
+        inputs_str += " " + File.join(autogen, "memory.c") + " " + File.join(autogen, "io.c")
+
+        defines = {
+            "CPU_Z80_STATIC" => 1,
+            "CPU_Z80_USE_LOCAL_HEADER" => 1
+        }
+
+        defines_str = defines.map { |d, v| "-D#{d}=#{v}" }.join(" ")
+
+        includes = [
+            "external/Z/API",
+            "external/z80/API",
+            "external/z80/API/emulation/CPU",
+            "."
+        ]
+
+        includes_str = includes.map { |i| "-I#{File.join(SRC, i)}" }.join(" ")
+
+        includes_str += " -I" + autogen
+
+        command = "#{compiler} -Werror -Wno-unknown-warning-option -fPIC -shared -Wl,-undefined -Wl,dynamic_lookup #{includes_str} #{defines_str} -o #{output} #{inputs_str}"
+        
+        # Run the compiler and generate a library.
+        return system(command)
+    end
+
+    # Generates the prerequisite source and header files for a given configuration.
+    #
+    # @param [Zemu::Config] configuration The configuration for which an emulator will be generated.
+    def Zemu::generate(configuration)
+        generate_memory(configuration)
+        generate_io(configuration)
+    end
+
+    # Generates the memory.c and memory.h files for a given configuration.
+    def Zemu::generate_memory(configuration)
+        header_template = ERB.new File.read(File.join(SRC, "memory.h.erb"))
+        source_template = ERB.new File.read(File.join(SRC, "memory.c.erb"))
+
+        autogen = File.join(configuration.output_directory, "autogen_#{configuration.name}")
+
+        unless Dir.exist? autogen
+            Dir.mkdir autogen
+        end
+
+        File.write(File.join(autogen, "memory.h"),
+                   header_template.result(configuration.get_binding))
+
+        File.write(File.join(autogen, "memory.c"),
+                   source_template.result(configuration.get_binding))
+    end
+
+    # Generates the io.c and io.h files for a given configuration.
+    def Zemu::generate_io(configuration)
+        header_template = ERB.new File.read(File.join(SRC, "io.h.erb"))
+        source_template = ERB.new File.read(File.join(SRC, "io.c.erb"))
+
+        autogen = File.join(configuration.output_directory, "autogen_#{configuration.name}")
+
+        unless Dir.exist? autogen
+            Dir.mkdir autogen
+        end
+
+        File.write(File.join(autogen, "io.h"),
+                   header_template.result(configuration.get_binding))
+
+        File.write(File.join(autogen, "io.c"),
+                   source_template.result(configuration.get_binding))
+    end
+end