avruby 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63999499c4aa4ad74832d1336a0831f70cb6d27db1c56289ce34990bc4067a88
+  data.tar.gz: ee091a1f40ced91acd72fb586a5dddb607df0c149c120c39ae94fee704033302
+SHA512:
+  metadata.gz: 6b9ef4be22b80c0360c4f0c171cf84c7bf988625598187955945f96b71ae3e708d2f9e23deadd6cfa543300e70bb9bb4d96b526335b4ab4a2e42ff561fb5138a
+  data.tar.gz: 0e4229b9af1f2c876db49d9f23b1133d08cf4270f1affa9115cfec5ba8a2a54b41ad58a2a3865792ebbd30954b087b66731e6526bb082492f4992a097f6fa57f

data/LICENSE.md

@@ -0,0 +1,28 @@
+This software is licensed under the Revised (3-clause) BSD license as follows:
+
+Copyright (c) 2019, Jeremy Cole <jeremy@jcole.us>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* Neither the name of the <organization> nor the
+  names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,17 @@
+# AVRuby
+
+[![Build Status](https://travis-ci.org/jeremycole/avruby.svg?branch=master)](https://travis-ci.org/jeremycole/avruby)
+
+## tl;dr
+
+This is an AVR emulator, written really stupidly in Ruby. It's not supposed to be practical, it's supposed to be educational, and maybe a bit of fun.
+
+## Status
+
+I initially started this as an exercise in parsing some opcodes, as I was learning how the AVR instruction set worked while learning AVR assembly. Once I could parse a few things, I thought "Hey, I could execute these in Ruby – haha!" and AVRuby was born.
+
+The CPU is nearly fully implemented. SRAM, Flash, and EEPROM memories are supported. Most opcodes work. Support for loading the flash (or any memory) from Intel hex is supported, so it's easy to load existing code. Basic RSpec tests are implemented for opcodes and some other things. Most peripherals are not implemented. Contributions (or insults) are welcome.
+
+Currently, many simple programs (such as blink) will run out of the box, although the CPU as emulated is exceedingly slow. It runs at ~140 kHz on a MacBook Pro with 2.8 GHz Intel Core i7 using Ruby 2.6.3.
+
+# It's fun.

data/bin/avruby_shell

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby
+# typed: strict
+# frozen_string_literal: true
+
+require 'optparse'
+require 'avr'
+require 'irb'
+require 'irb/completion'
+require 'pp'
+
+def initialize_device
+  print 'Initializing device... '
+  @device = AVR::Device::Atmel_ATmega328p.new
+  @cpu = @device.cpu
+  puts 'OK.'
+end
+
+def load_intel_hex_files(files)
+  puts 'Loading Intel hex firmware into Flash...'
+  files.each do |hex_file|
+    print "- Loading #{hex_file}... "
+    bytes_loaded = @device.flash.load_from_intel_hex(hex_file)
+    puts "OK, loaded #{bytes_loaded} bytes."
+  end
+end
+
+def enable_tracing
+  print 'Setting up tracing... '
+  @device.trace_all
+  puts 'OK.'
+end
+
+def shell
+  puts 'Typically, you should:'
+  puts '  Use @device to access the entire device.'
+  puts '  Use @cpu (or @device.cpu) to access the CPU.'
+  puts '  Some useful things to run:'
+  puts '    @device.oscillator.tick to single step.'
+  puts '    @device.oscillator.run(5.times) to run for 5 ticks.'
+  puts '    @device.oscillator.run to run indefinitely.'
+  puts 'Ready. Have fun!'
+  puts
+
+  irb = IRB::Irb.new
+  irb.run(IRB.conf)
+
+  puts 'Stopped.'
+  puts
+end
+
+def benchmark_warmup
+  print 'Warming up for %0.1f seconds... ' % [@options[:benchmark_warmup_time]]
+  warmup_ticks = @device.oscillator.run_timed(@options[:benchmark_warmup_time])
+  puts 'OK.'
+
+  puts 'Execution speed during warmup: %.2f kHz' % [
+    warmup_ticks.to_f / @options[:benchmark_warmup_time] / 1000.0,
+  ]
+  puts
+end
+
+def benchmark_time
+  print 'Benchmarking for %0.1f seconds... ' % [@options[:benchmark_time]]
+  benchmark_ticks = @device.oscillator.run_timed(@options[:benchmark_time])
+  puts 'OK.'
+
+  puts 'Execution speed: %.2f kHz over %0.2f seconds' % [
+    benchmark_ticks.to_f / @options[:benchmark_time] / 1000.0,
+    @options[:benchmark_time],
+  ]
+  puts
+end
+
+def benchmark_ticks
+  print 'Benchmarking for %d ticks... ' % [@options[:benchmark_ticks]]
+  start_time = Time.now.to_f
+  @device.oscillator.run(@options[:benchmark_ticks].times)
+  end_time = Time.now.to_f
+  puts 'OK.'
+
+  benchmark_time = end_time - start_time
+
+  puts 'Execution speed: %.2f kHz over %0.2f seconds' % [
+    @options[:benchmark_ticks].to_f / benchmark_time / 1000.0,
+    benchmark_time,
+  ]
+  puts
+end
+
+def benchmark
+  benchmark_warmup if @options[:benchmark_warmup_time]
+  benchmark_time if @options[:benchmark_time]
+  benchmark_ticks if @options[:benchmark_ticks]
+end
+
+def print_opcode_decoder_cache
+  @device.cpu.decoder.print_cache
+  puts
+end
+
+IRB.setup(nil, argv: ['-f'])
+
+IRB.conf[:IRB_NAME] = 'avr'
+IRB.conf[:SAVE_HISTORY] = 1000
+IRB.conf[:HISTORY_FILE] = File.join(ENV['HOME'], '.avruby_shell_history')
+IRB.conf[:PROMPT][:avruby_shell] = {
+  PROMPT_I: "\u001b[0;34;1m%N>\u001b[0m ",
+  PROMPT_N: "\u001b[0;34;1m%N>\u001b[0m ",
+  PROMPT_S: "\u001b[0;33;1m%N+\u001b[0m ",
+  PROMPT_C: "\u001b[0;35;1m%N*\u001b[0m ",
+  RETURN: "\u001b[0;31;1m=>\u001b[0m \u001b[32m%s\u001b[0m\n\n",
+}
+IRB.conf[:PROMPT_MODE] = :avruby_shell
+
+@options = {
+  trace: false,
+  benchmark_time: nil,
+  benchmark_ticks: nil,
+  benchmark_warmup_time: nil,
+  benchmark_print_opcode_cache: false,
+  intel_hex_files: [],
+}
+
+OptionParser.new do |opts|
+  opts.on('-h', '--help', 'Show this help.') do
+    puts opts
+    puts
+    exit
+  end
+  opts.on('-b', '--benchmark-time=TIME', 'Specify the run time, in seconds.') do |o|
+    @options[:benchmark_time] = o.to_f
+  end
+  opts.on('-B', '--benchmark-ticks=TICKS', 'Specify the run time, in ticks.') do |o|
+    @options[:benchmark_ticks] = o.to_i
+  end
+  opts.on('-w', '--benchmark-warmup-time=TIME', 'Specify the warmup time, in seconds.') do |o|
+    @options[:benchmark_warmup_time] = o.to_f
+  end
+  opts.on('-d', '--[no-]benchmark-print-opcode-cache', 'Enable print of opcode decoder cache after benchmark.') do |o|
+    @options[:benchmark_print_opcode_cache] = o
+  end
+  opts.on('-t', '--[no-]trace', 'Enable tracing.') do |o|
+    @options[:trace] = o
+  end
+  opts.on('-I', '--intel-hex-file=FILE', 'Load Intel hex file.') do |o|
+    @options[:intel_hex_files] << o
+  end
+end.parse!
+
+initialize_device
+load_intel_hex_files(@options[:intel_hex_files]) unless @options[:intel_hex_files].empty?
+enable_tracing if @options[:trace]
+
+puts
+
+if @options[:benchmark_time] || @options[:benchmark_ticks]
+  benchmark
+else
+  shell
+end
+
+print_opcode_decoder_cache if @options[:benchmark_print_opcode_cache]

data/lib/avr.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+if ENV.include?('SORBET_DEFAULT_CHECKED_LEVEL')
+  level = ENV.fetch('SORBET_DEFAULT_CHECKED_LEVEL').to_sym
+  puts "Setting Sorbet default_checked_level to :#{level}!"
+  puts
+
+  T::Configuration.default_checked_level = level
+end
+
+require 'avr/version'
+require 'avr/value'
+require 'avr/memory'
+require 'avr/memory/sram'
+require 'avr/memory/eeprom'
+require 'avr/memory/flash'
+require 'avr/register'
+require 'avr/register_with_bit_number'
+require 'avr/register_with_displacement'
+require 'avr/register_with_modification'
+require 'avr/register/memory_byte_register'
+require 'avr/register/memory_byte_register_with_named_bits'
+require 'avr/register_with_named_bit'
+require 'avr/register/register_pair'
+require 'avr/register/register_file'
+require 'avr/register/sreg'
+require 'avr/register/sp'
+require 'avr/argument'
+require 'avr/cpu'
+require 'avr/opcode_decoder'
+require 'avr/opcode'
+require 'avr/instruction'
+require 'avr/opcode/opcodes'
+require 'avr/clock'
+require 'avr/oscillator'
+require 'avr/device'
+require 'avr/port'
+
+require 'avr/device/atmel_atmega328p'

data/lib/avr/argument.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AVR
+  module Argument
+    extend T::Sig
+
+    ValueType = T.type_alias do
+      T.any(
+        Value,
+        Register,
+        RegisterPair,
+        MemoryByteRegister,
+        RegisterWithDisplacement,
+        RegisterWithModification,
+        RegisterWithBitNumber,
+        RegisterWithNamedBit
+      )
+    end
+    ArrayType = T.type_alias { T::Array[ValueType] }
+    NamedValueType = T.type_alias { T::Hash[Symbol, ValueType] }
+  end
+end

data/lib/avr/clock.rb

@@ -0,0 +1,99 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AVR
+  class Clock
+    extend T::Sig
+
+    class Sink
+      extend T::Sig
+
+      sig do
+        params(
+          name: T.nilable(String),
+          sink_proc: T.nilable(T.proc.params(source: Clock, ticks: Integer).void),
+          block: T.nilable(T.proc.params(source: Clock, ticks: Integer).void)
+        ).void
+      end
+      def initialize(name = nil, sink_proc = nil, &block)
+        raise unless sink_proc || block_given?
+        @name = name
+        @sink_proc = T.let(
+          sink_proc || block&.to_proc,
+          T.nilable(T.proc.params(source: Clock, ticks: Integer).void)
+        )
+      end
+
+      sig { params(source: Clock, ticks: Integer).void }
+      def tick(source, ticks)
+        T.must(@sink_proc).call(source, ticks)
+      end
+    end
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :name
+
+    sig { returns(T::Array[T.any(Clock, Sink)]) }
+    attr_reader :sinks
+
+    sig { returns(T::Hash[Integer, T.untyped]) }
+    attr_reader :watches
+
+    sig { returns (Integer) }
+    attr_accessor :count
+
+    sig { returns (Integer) }
+    attr_accessor :ticks
+
+    sig { returns (Integer) }
+    attr_accessor :scale
+
+    sig { params(name: T.nilable(String)).void }
+    def initialize(name = nil)
+      @name = name
+      @sinks = T.let([], T::Array[Sink])
+      @watches = T.let({}, T::Hash[Integer, T.untyped])
+      @ticks = T.let(0, Integer)
+      @count = T.let(0, Integer)
+      @scale = T.let(1, Integer)
+      @last_tick = T.let(0, Integer)
+    end
+
+    sig { params(sink: Sink).void }
+    def unshift_sink(sink)
+      sinks.unshift(sink)
+    end
+
+    sig { params(sink: T.any(Clock, Sink)).void }
+    def push_sink(sink)
+      sinks.push(sink)
+    end
+
+    sig { void }
+    def clear_sinks
+      @sinks = []
+    end
+
+    sig { params(tick: Integer, sink: Sink).void }
+    def notify_at_tick(tick, sink)
+      @watches[tick] ||= []
+      @watches[tick] << sink
+    end
+
+    sig { params(_source: T.nilable(Clock), _ticks: T.nilable(Integer)).returns(Integer) }
+    def tick(_source = nil, _ticks = nil)
+      @count += 1
+      if (@count % @scale).zero?
+        @last_tick = @ticks
+        sinks.each do |sink|
+          sink.tick(self, @ticks)
+        end
+        watches[@ticks]&.each do |watch|
+          watch.tick(self, @ticks)
+        end
+        @ticks += 1
+      end
+      @last_tick
+    end
+  end
+end

data/lib/avr/cpu.rb

@@ -0,0 +1,254 @@
+# typed: false
+# frozen_string_literal: true
+
+module AVR
+  class CPU
+    extend T::Sig
+
+    sig { returns(Device) }
+    attr_reader :device
+
+    sig { returns(Integer) }
+    attr_accessor :pc
+
+    sig { returns(Integer) }
+    attr_accessor :next_pc
+
+    sig { returns(Memory) }
+    attr_reader :sram
+
+    sig { returns(RegisterFile) }
+    attr_reader :registers
+
+    sig { returns(Register) }
+    def r0
+      registers.fetch(:r0)
+    end
+
+    sig { params(value: Integer).void }
+    def r0=(value)
+      registers.fetch(:r0).value = value
+    end
+
+    sig { returns(Register) }
+    def r1
+      registers.fetch(:r1)
+    end
+
+    sig { params(value: Integer).void }
+    def r1=(value)
+      registers.fetch(:r1).value = value
+    end
+
+    sig { returns(Register) }
+    def X
+      registers.fetch(:X)
+    end
+
+    sig { returns(Register) }
+    def Y
+      registers.fetch(:Y)
+    end
+
+    sig { returns(Register) }
+    def Z
+      registers.fetch(:Z)
+    end
+
+    sig { returns(RegisterFile) }
+    attr_reader :io_registers
+
+    # SREG uses metaprogramming that Sorbet doesn't understand
+    # sig { returns(SREG) }
+    sig { returns(T.untyped) }
+    attr_reader :sreg
+
+    sig { returns(SP) }
+    attr_reader :sp
+
+    sig { returns(OpcodeDecoder) }
+    attr_reader :decoder
+
+    sig { returns(T::Hash[Symbol, Port]) }
+    attr_reader :ports
+
+    sig { returns(Clock) }
+    attr_reader :clock
+
+    sig { returns(T.nilable(T.proc.params(arg0: Instruction).void)) }
+    attr_reader :tracer
+
+    sig { params(device: Device).void }
+    def initialize(device)
+      @device = device
+      @pc = 0
+      @next_pc = 0
+      @sram = SRAM.new(device.ram_start + device.sram_size)
+
+      @registers = RegisterFile.new(self)
+
+      device.register_count.times do |n|
+        registers.add(MemoryByteRegister.new(self, "r#{n}", @sram.memory[n]))
+      end
+
+      device.word_register_map.each do |name, map|
+        registers.add(RegisterPair.new(self, @registers[map[:l]], @registers[map[:h]], name))
+      end
+
+      @io_registers = RegisterFile.new(self)
+      device.io_registers.each do |name|
+        address = device.data_memory_map[name]
+        next unless address
+
+        bit_names = device.register_bit_names_map[name]
+        if bit_names
+          io_registers.add(MemoryByteRegisterWithNamedBits.new(self, name.to_s, @sram.memory[address], bit_names))
+        else
+          io_registers.add(MemoryByteRegister.new(self, name.to_s, @sram.memory[address]))
+        end
+      end
+
+      @sreg = SREG.new(self)
+
+      @sp = SP.new(
+        self,
+        @sram.memory[device.data_memory_map[:SPL]],
+        @sram.memory[device.data_memory_map[:SPH]],
+        device.ram_end
+      )
+
+      @decoder = OpcodeDecoder.new
+
+      @ports = {}
+      device.port_map.each do |name, addr|
+        @ports[name] = Port.new(self, name, addr[:pin], addr[:ddr], addr[:port])
+      end
+
+      @clock = Clock.new('cpu')
+      @clock.push_sink(Clock::Sink.new('cpu') { step })
+
+      @tracer = nil
+    end
+
+    def notify_at_tick(tick, &block)
+      clock.notify_at_tick(tick, Clock::Sink.new("notify #{block} at #{tick}", block.to_proc))
+    end
+
+    sig { params(block: T.nilable(T.proc.params(arg0: Instruction).void)).void }
+    def trace(&block)
+      @tracer = nil
+      @tracer = block.to_proc if block_given?
+    end
+
+    sig { void }
+    def print_status
+      puts 'Status:'
+      puts '%8s = %d' % ['Ticks', clock.ticks]
+      puts '%8s = %d opcodes' % ['Cache', decoder.cache.size]
+      puts '%8s = 0x%04x words' % ['PC', pc]
+      puts '%8s = 0x%04x bytes' % ['PC', pc * 2]
+      puts '%8s = 0x%04x (%d bytes used)' % ['SP', sp.value, device.ram_end - sp.value]
+      puts '%8s = 0x%02x [%s]' % ['SREG', sreg.value, sreg.bit_values]
+      puts
+      puts 'Registers:'
+      registers.print_status
+      puts
+      puts 'IO Registers:'
+      io_registers.print_status
+      puts
+      puts 'IO Ports:'
+      puts '%4s  %s' % ['', Port::PINS.join(' ')]
+      ports.each do |name, port|
+        puts '%4s: %s' % [name, port.pin_states.join(' ')]
+      end
+      puts
+      puts 'Next instruction:'
+      puts '  ' + peek.to_s
+      puts
+    end
+
+    sig { void }
+    def reset_to_clean_state
+      reset
+      registers.reset
+      io_registers.reset
+      sram.reset
+      sp.value = device.ram_end
+    end
+
+    sig { void }
+    def reset
+      @pc = 0
+      @next_pc = 0
+      sreg.reset
+    end
+
+    sig { returns(Integer) }
+    def fetch
+      word = device.flash.word(next_pc)
+      @next_pc += 1
+      word
+    end
+
+    sig { params(mnemonic: Symbol, args: T.untyped).returns(Instruction) }
+    def instruction(mnemonic, *args)
+      Instruction.new(self, mnemonic, args)
+    end
+
+    sig { params(name_or_vector_number: T.any(Symbol, Integer)).void }
+    def interrupt(name_or_vector_number)
+      sreg.I = false
+      case name_or_vector_number
+      when Integer
+        address = name_or_vector_number * 2
+      when Symbol
+        address = device.interrupt_vector_map[name_or_vector_number]
+      end
+
+      instruction(:call, Value.new(address)).execute
+    end
+
+    sig { returns(Instruction) }
+    def decode
+      offset = next_pc
+      word = fetch
+      decoded_opcode = decoder.decode(word)
+      unless decoded_opcode
+        raise 'Unable to decode 0x%04x at offset 0x%04x words (0x%04x bytes)' % [
+          word,
+          offset,
+          offset * 2,
+        ]
+      end
+
+      decoded_opcode.opcode_definition.parse(
+        self,
+        decoded_opcode.opcode_definition,
+        decoded_opcode.prepare_operands(self)
+      )
+    end
+
+    sig { returns(Instruction) }
+    def peek
+      save_pc = pc
+      save_next_pc = next_pc
+      i = decode
+      @pc = save_pc
+      @next_pc = save_next_pc
+      i
+    end
+
+    sig { void }
+    def step
+      i = decode
+      @tracer&.call(i)
+      begin
+        i.execute
+      rescue StandardError
+        puts "*** Caught exception while executing #{i}, CPU status:"
+        print_status
+        raise
+      end
+    end
+  end
+end