Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.Label` The `Label` class represents a label within the `Program` instance that encapsulates it.
`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.
`protected byte[]` | `data` The `data` field stores a reference to the array that contains the raw data (bytes) of the program segment.
`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 Instr[]` | `instrs` The `instrs` field stores a reference to the array that contains the instruction representations of the program segment.
`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.
`void` | `dump()` The `dump()` method prints out a textual dump of the program.
`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.Label` | `getLabel(java.lang.String name)` The `getLabel()` method searches for a label with a given name within the program, in any section.
`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.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` | `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

### 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.

### data

    protected final byte[] data

  The `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.

### instrs

    protected final Instr[] instrs

  The `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.Label 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

### 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

### dump

    public void dump()

  The `dump()` method prints out a textual dump of the program. It is useful for debugging the program building process.

### 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD