avrora.core
Class Program

java.lang.Object
  avrora.core.Program

public class Program

extends java.lang.Object

The Program class represents a complete program of AVR instructions. It stores the actual instructions and initialized data of the program in one instr4 segment, as well as storing the data space and eeprom space requirements for the program. It contains a map of labels (strings) to addresses, which can be either case sensitive (GAS style) or case insensitive (Atmel style).

See Also:

Instr, ControlFlowGraph, ProcedureMap

Nested Class Summary

class	Program.DataLabel The DataLabel class represents a label within the program that refers to the data segment.
class	Program.EEPromLabel The EEPromLabel class represents a label within the program that refers to the eeprom segment.
class	Program.Location The Location class represents a location in the program; either named by a label, or an unnamed integer address.
class	Program.ProgramLabel The ProgramLabel class represents a label within the program that refers to the program segment.

Field Summary

boolean	caseSensitive The caseSensitive field controls whether label searching is case sensitive or not.
int	data_end The data_end field records the address following the highest address in the program with declared, labelled memory in the data segment.
int	data_start The data_start field records the lowest address of declared, labelled memory in the data segment.
int	eeprom_end The eeprom_end field records the address following the highest address in the program with declared, labelled memory in the eeprom segment.
int	eeprom_start The eeprom_start field records the lowest address of declared, labelled memory in the eeprom segment.
protected byte[]	flash_data The flash_data field stores a reference to the array that contains the raw data (bytes) of the program segment.
protected Instr[]	flash_instrs The flash_instrs field stores a reference to the array that contains the instruction representations of the program segment.
static java.util.Comparator	LOCATION_COMPARATOR The LOCATION_COMPARATOR comparator is used in order to sort locations in the program from lowest address to highest address.
int	program_end The program_end field records the address following the highest address in the program segment that contains valid code or data.
int	program_length The program_length field records the size of the program (the difference between program_start and program_end.
int	program_start The program_start field records the lowest address in the program segment that contains valid code or data.

Constructor Summary

Program(int pstart, int pend, int dstart, int dend, int estart, int eend)
The constructor of the Program class builds an internal representation of the program that is initially empty, but has the given parameters in terms of how big segments are and where they start.

Method Summary

void	addIndirectEdge(int callsite, int target) The addIndirectEdge adds an indirect edge between a callsite and possible target.
protected void	checkAddress(int addr) The checkAddress() method simply checks an address against the bounds of the program and throws an error if the address is not within the bounds.
ControlFlowGraph	getCFG() The getCFG() method returns a reference to the control flow graph of the program.
java.util.List	getIndirectEdges(int callsite) The getIndirectEdges returns a list of integers representing the possible target program locations for a given callsite.
Program.Location	getLabel(java.lang.String name) The getLabel() method searches for a label with a given name within the program, in any section.
java.util.HashMap	getLabels()
int	getNextPC(int pc) The getNextPC() method computes the program counter value of the next instruction following the instruction referenced by the given program counter value.
Program.Location	getProgramLocation(java.lang.String s) The getProgramLocation() method will convert the specified string into a program location, i.e. a location in the program segment.
SourceMapping	getSourceMapping()
Program.DataLabel	newDataLabel(java.lang.String name, int byteAddress) The newDataLabel() method creates a label in the data segment with the specified name at the specified byte address.
Program.EEPromLabel	newEEPromLabel(java.lang.String name, int byteAddress) The newEEPromLabel() method creates a label in the eeprom segment with the specified name at the specified byte address.
Program.ProgramLabel	newProgramLabel(java.lang.String name, int byteAddress) The newProgramLabel() method creates a label in the program segment with the specified name at the specified byte address.
Instr	readInstr(int address) The readInstr() method reads an instruction from the specified address in the program.
byte	readProgramByte(int address) The readProgramByte() method reads a byte into the program segment at the specified byte address.
void	setSourceMapping(SourceMapping s)
void	writeInstr(Instr i, int address) The writeInstr() method is used to write an instruction to the internal representation of the program at the given address.
void	writeProgramByte(byte val, int byteAddress) The writeProgramByte() method writes a byte into the program segment at the specified byte address.
void	writeProgramBytes(byte[] val, int byteAddress) The writeProgramBytes() method writes an array of bytes into the program segment at the specified byte address.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCATION_COMPARATOR

public static java.util.Comparator LOCATION_COMPARATOR

The LOCATION_COMPARATOR comparator is used in order to sort locations in the program from lowest address to highest address.

program_start

public final int program_start

The program_start field records the lowest address in the program segment that contains valid code or data.

program_end

public final int program_end

The program_end field records the address following the highest address in the program segment that contains valid code or data.

program_length

public final int program_length

The program_length field records the size of the program (the difference between program_start and program_end.

data_start

public final int data_start

The data_start field records the lowest address of declared, labelled memory in the data segment.

data_end

public final int data_end

The data_end field records the address following the highest address in the program with declared, labelled memory in the data segment.

eeprom_start

public final int eeprom_start

The eeprom_start field records the lowest address of declared, labelled memory in the eeprom segment.

eeprom_end

public final int eeprom_end

The eeprom_end field records the address following the highest address in the program with declared, labelled memory in the eeprom segment.

flash_data

protected final byte[] flash_data

The flash_data field stores a reference to the array that contains the raw data (bytes) of the program segment. NO EFFORT IS MADE IN THIS CLASS TO KEEP THIS CONSISTENT WITH THE INSTRUCTION REPRESENTATIONS.

flash_instrs

protected final Instr[] flash_instrs

The flash_instrs field stores a reference to the array that contains the instruction representations of the program segment. NO EFFORT IS MADE IN THIS CLASS TO KEEP THIS CONSISTENT WITH THE RAW DATA OF THE PROGRAM SEGMENT.

caseSensitive

public boolean caseSensitive

The caseSensitive field controls whether label searching is case sensitive or not. Some program representations use case sensitive labels, and some do not.

Constructor Detail

Program

public Program(int pstart,
               int pend,
               int dstart,
               int dend,
               int estart,
               int eend)

The constructor of the Program class builds an internal representation of the program that is initially empty, but has the given parameters in terms of how big segments are and where they start.

Parameters:

pstart - the start of the program segment

pend - the end of the program segment

dstart - the start of the data segment

dend - the end of the data segment

estart - the start of the eeprom segment

eend - the end of the eeprom segment

Method Detail

writeInstr

public void writeInstr(Instr i,
                       int address)

The writeInstr() method is used to write an instruction to the internal representation of the program at the given address. No attempt to assemble the instruction machine code is made; thus the raw data (if any) at that location in the program will not be modified.

Parameters:

i - the instruction to write

address - the byte address to write the instruction to that must be aligned on a 2-byte boundary.

Throws:

Avrora.InternalError - if the address is not within the limits put on the program instance when it was created.

readInstr

public Instr readInstr(int address)

The readInstr() method reads an instruction from the specified address in the program. No attempt to disassemble raw data into usable instructions is made, and unaligned accesses will return null.

Parameters:

address - the byte address in the program

Returns:

the Instr instance at that address if that address is valid code from creation of the Program instance; null if the instruction is misaligned or only raw data is present at that location.

Throws:

Avrora.InternalError - if the address is not within the limits put on the program instance when it was created.

readProgramByte

public byte readProgramByte(int address)

The readProgramByte() method reads a byte into the program segment at the specified byte address. If the address overlaps with an instruction, no effort is made to get the correct encoded byte of the instruction.

Parameters:

address - the program address from which to read the byte

Returns:

the byte value of the program segment at that location

writeProgramByte

public void writeProgramByte(byte val,
                             int byteAddress)

The writeProgramByte() method writes a byte into the program segment at the specified byte address. If the address overlaps with an instruction, no effort is made to keep the instruction representation up to date.

Parameters:

val - the value to write

byteAddress - the byte address in the program segment to write the byte value to

writeProgramBytes

public void writeProgramBytes(byte[] val,
                              int byteAddress)

The writeProgramBytes() method writes an array of bytes into the program segment at the specified byte address. If the range of addresses modified overlaps with any instructions, no effort is made to keep the instruction representations up to date.

Parameters:

val - the byte values to write

byteAddress - the byte address to begin writing the values to

newProgramLabel

public Program.ProgramLabel newProgramLabel(java.lang.String name,
                                            int byteAddress)

The newProgramLabel() method creates a label in the program segment with the specified name at the specified byte address.

Parameters:

name - the name of the label

byteAddress - the byte address to associate with the label

Returns:

an instance of the ProgramLabel class corresponding to this new label

newDataLabel

public Program.DataLabel newDataLabel(java.lang.String name,
                                      int byteAddress)

The newDataLabel() method creates a label in the data segment with the specified name at the specified byte address.

Parameters:

name - the name of the label

byteAddress - the byte address to associate with the label

Returns:

an instance of the DataLabel class corresponding to this new label

newEEPromLabel

public Program.EEPromLabel newEEPromLabel(java.lang.String name,
                                          int byteAddress)

The newEEPromLabel() method creates a label in the eeprom segment with the specified name at the specified byte address.

Parameters:

name - the name of the label

byteAddress - the byte address to associate with the label

Returns:

an instance of the EEPromLabel class corresponding to this new label

getLabel

public Program.Location getLabel(java.lang.String name)

The getLabel() method searches for a label with a given name within the program, in any section.

Parameters:

name - the string name of the label

Returns:

an instance of Label if the label exists; null otherwise

getProgramLocation

public Program.Location getProgramLocation(java.lang.String s)

The getProgramLocation() method will convert the specified string into a program location, i.e. a location in the program segment. If the string begins with "0x", then it is considered a hexadecimal address and a location will be returned that corresponds to that address in the program segment. Otherwise, the string is considered to be a string and the method will attempt to look for a label with that name.

Parameters:

s - the string name to look up in the program segment

Returns:

an instance of the Location representing that location in the program segment if the string was either a hexadecimal constant or a valid label in the program segment; null otherwise

checkAddress

protected void checkAddress(int addr)

The checkAddress() method simply checks an address against the bounds of the program and throws an error if the address is not within the bounds.

Parameters:

addr - the byte address to check

Throws:

Avrora.InternalError - if the address is not within the limits of the program segment

getNextPC

public int getNextPC(int pc)

The getNextPC() method computes the program counter value of the next instruction following the instruction referenced by the given program counter value. Thus, it simply adds the size of the instruction at the specified pc to the pc. It is useful as a commonly-used utility method.

Parameters:

pc - the program counter location of the current instruction

Returns:

the program counter value of the instruction following the specified instruction in program order

getIndirectEdges

public java.util.List getIndirectEdges(int callsite)

The getIndirectEdges returns a list of integers representing the possible target program locations for a given callsite. This is auxilliary information that is supplied at the command line which is used for a variety of analysis questions.

Parameters:

callsite - the program counter location of an indirect branch or call

Returns:

a list of java.lang.Integer objects that represent the possible targets of the call or branch instruction

addIndirectEdge

public void addIndirectEdge(int callsite,
                            int target)

The addIndirectEdge adds an indirect edge between a callsite and possible target. This is auxilliary information that is supplied at the command line which is used for a variety of analysis questions.

Parameters:

callsite - the program counter location of the call or branch instruction

target - the possible target of the call or branch instruction

getSourceMapping

public SourceMapping getSourceMapping()

setSourceMapping

public void setSourceMapping(SourceMapping s)

getCFG

public ControlFlowGraph getCFG()

The getCFG() method returns a reference to the control flow graph of the program. This is an instance of ControlFlowGraph that is constructed lazily--i.e. the first time this method is called. No effort is made to keep the control flow graph up to date with a changing program representation; adding instructions or writing bytes into the program segment of the program will not alter the CFG once it has been constructed.

Returns:

a reference to the ControlFlowGraph instance that represents the control flow graph for this program

getLabels

public java.util.HashMap getLabels()