Class: RPicSim::ProgramFile

Inherits:
Object
  • Object
show all
Defined in:
lib/rpicsim/program_file.rb

Overview

Represents a PIC program file (e.g. COF or HEX). Keeps track of all the symbols loaded from that file and also allows you to add symbols in various ways.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(filename, device) ⇒ ProgramFile

Returns a new instance of ProgramFile

Parameters:

  • filename (String) —

    The path to the program file.

  • device (String) —

    The name of the device the file is for (e.g. “PIC10F322”).



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/rpicsim/program_file.rb', line 29

def initialize(filename, device)
  @filename = filename
  @device = device

  @mplab_program_file = Mplab::MplabProgramFile.new(filename, device)

  @assembly = Mplab::MplabAssembly.new(device)
  @assembly.load_file(filename)
  @address_increment = @assembly.device_info.code_address_increment

  @labels = {}

  @symbol_set = SymbolSet.new
  @symbol_set.def_memory_type :ram
  @symbol_set.def_memory_type :program_memory
  @symbol_set.def_memory_type :eeprom

  @symbol_set.on_symbol_definition do |name, address, memory_type|
    if memory_type == :program_memory
      labels[name] = Label.new(name, address)
    end
  end

  import_symbols @mplab_program_file
end

Instance Attribute Details

#device ⇒ String (readonly)

The name of the device the file is for (e.g. “PIC10F322”).

Returns:

  • (String) 


22
23
24
 
# File 'lib/rpicsim/program_file.rb', line 22

def device
  @device
end

#filename ⇒ String (readonly)

Returns:

  • (String) 


17
18
19
 
# File 'lib/rpicsim/program_file.rb', line 17

def filename
  @filename
end

#labels ⇒ Hash (readonly)

Returns a hash associating program memory label names (as symbols) to their addresses.

Returns:

  • (Hash) 


144
145
146
 
# File 'lib/rpicsim/program_file.rb', line 144

def labels
  @labels
end

Instance Method Details

#address_description(address) ⇒ String

Generates a friendly human-readable string description of the given address in program memory.

Parameters:

  • address (Integer) —

    An address in program memory.

Returns:

  • (String) 


164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/rpicsim/program_file.rb', line 164

def address_description(address)
  desc = address < 0 ? address.to_s : ('0x%04x' % [address])
  reference_points = labels.values.reject { |label| label.address > address }
  label = reference_points.max_by(&:address)

  if label
    offset = address - label.address
    desc << ' = ' + label.name.to_s
    desc << '+%#x' % [offset] if offset != 0
  end

  desc
end

#def_symbol(name, address, memory_type = nil) ⇒ Object

Defines a new symbol.

Parameters:

  • name (Symbol) —

    The name of the symbol.

  • address (Integer) —

    The address of the symbol.

  • memory_type (Symbol) (defaults to: nil) —

    (optional) The type of memory the symbol belongs to. This should either by :ram, :program_memory, or :eeprom.



88
89
90
 
# File 'lib/rpicsim/program_file.rb', line 88

def def_symbol(name, address, memory_type = nil)
  @symbol_set.def_symbol name, address, memory_type
end

#import_symbols(symbol_source) ⇒ Object

Imports symbols from an additional symbol source.

The symbol_source parameter should be an object that responds to some subset of these methods: #symbols, #symbols_in_ram, #symbols_in_program_memory, #symbols_in_eeprom. The methods should take no arguments and return a hash where the keys are symbol names (represented as Ruby symbols) and the values are addresses (as integers).



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/rpicsim/program_file.rb', line 63

def import_symbols(symbol_source)
  if symbol_source.respond_to?(:symbols)
    @symbol_set.def_symbols symbol_source.symbols
  end

  if symbol_source.respond_to?(:symbols_in_ram)
    @symbol_set.def_symbols symbol_source.symbols_in_ram, :ram
  end

  if symbol_source.respond_to?(:symbols_in_program_memory)
    @symbol_set.def_symbols symbol_source.symbols_in_program_memory, :program_memory
  end

  if symbol_source.respond_to?(:symbols_in_eeprom)
    @symbol_set.def_symbols symbol_source.symbols_in_eeprom, :eeprom
  end
end

#label(name) ⇒ Label

Returns a Label object if a program label by that name is found. The name is specified in the code that defined the label. If you are using a C compiler, you will probably need to prefix the name with an underscore.

Returns:



151
152
153
154
155
156
157
158
 
# File 'lib/rpicsim/program_file.rb', line 151

def label(name)
  name = name.to_sym
  label = labels[name]
  if !label
    raise ArgumentError, message_for_label_not_found(name)
  end
  label
end

#symbols ⇒ Hash

Returns all the symbols known to the simulation.

The return value is a hash where the keys are the names of the symbols (represented as Ruby symbols) and the values are the addresses of the symbols.

Warning: This is a persistent hash that will automatically be updated when new symbols are defined.

Returns:

  • (Hash) 


101
102
103
 
# File 'lib/rpicsim/program_file.rb', line 101

def symbols
  @symbol_set.symbols
end

#symbols_in_eeprom ⇒ Hash

Returns all the symbols in EEPROM. The return value is a hash where the keys are the names of the symbols (represented as Ruby symbols) and the values are the addresses of the symbols.

Warning: This is a persistent hash that will automatically be updated when new symbols are defined.

Returns:

  • (Hash) 


137
138
139
 
# File 'lib/rpicsim/program_file.rb', line 137

def symbols_in_eeprom
  @symbol_set.symbols_in_memory(:eeprom)
end

#symbols_in_program_memory ⇒ Hash

Returns all the symbols in program memory. The return value is a hash where the keys are the names of the symbols (represented as Ruby symbols) and the values are the addresses of the symbols.

Warning: This is a persistent hash that will automatically be updated when new symbols are defined.

Returns:

  • (Hash) 


125
126
127
 
# File 'lib/rpicsim/program_file.rb', line 125

def symbols_in_program_memory
  @symbol_set.symbols_in_memory(:program_memory)
end

#symbols_in_ram ⇒ Hash

Returns all the symbols in RAM. The return value is a hash where the keys are the names of the symbols (represented as Ruby symbols) and the values are the addresses of the symbols.

Warning: This is a persistent hash that will automatically be updated when new symbols are defined.

Returns:

  • (Hash) 


113
114
115
 
# File 'lib/rpicsim/program_file.rb', line 113

def symbols_in_ram
  @symbol_set.symbols_in_memory(:ram)
end