ASM Scope users' manual

Dan Muresan


Table of Contents

The graphical interface
Commands
Supported languages
Known issues

ASM Scope is a Java/Swing application that analyzes assembly programs. It extracts structural information from “spaghetti-style” assembly code and presents a hierarchical view of the program; analyzes control flow and displays a call graph; and tracks data flow for any subset of the program. ASM Scope can be used as a debugging aid or as a reverse-engineering tool when working with unfamiliar code.

The graphical interface

The ASM Scope main window consists of five panes:

  1. the code pane displays the program

  2. the subroutines pane contains bookmarks pointing to subroutines

  3. the labels pane contains bookmarks pointing to all labels

  4. the control pane contains command buttons

  5. the status pane displays general information or show the results of the most recently performed operation

Additionally, there is a separate call graph window.

The code pane

The code pane normally displays a hierarchical (tree-like) view of the program: the root of the tree is the MODULE directive; subroutines are displayed as first-level nodes; individual statements are generally on the second level, but can also be folded (see below). A line number displayed on the left-hand side identifies each statement.

A fold is a group of statements that share a common purpose and are displayed as a sub-tree in the code pane. The first statement in the fold is the root of the sub-tree, the other statements are child nodes. Folds can be displayed collapsed (showing only the root) or expanded (showing the root and all children). ASM Scope automatically creates folds upon loading a new file when it identifies standard control structures (such as a DO loop or an if-then-else branch). You can also create and remove folds manually.

You can select a statement or a range of statements by clicking on them; the selected statements will be highlighted. The selection can be continuous or discontinuous. The command buttons in the control pane analyze the selection and possibly change it.

Editor

The default mode of the code pane is the tree view. You can activate the editor mode using the Edit/Parse button. While in editor mode, the code pane temporarily displays a text editor instead of the normal tree view; in this mode, the code pane is also called the editor pane.

The editor works on a virtual file, independent of the code displayed in the tree view (that code, if any, is lost when you click the Edit button). You cannot save the edited text to a file directly; as a workaround, you can copy the text and paste it into another program.

The bookmark panes

The labels and subroutines panes have navigational functions: clicking on a label will select the line in the code pane defining that label.

The subroutines pane displays an alphabetical list of all subroutines in the program; a label is considered a subroutine if it is either declared global or is being used in a CALL statement. Global subroutines have an asterisk appended to their names.

The labels pane lists all labels that occur in the program.

The control pane

The control pane normally contains a number of command buttons that operate on the selection. Some buttons change the active selection, while others analyze the selection and add context-dependent buttons to the control pane.

The status pane

The status pane contains two lines that either

  • display general status information or error conditions (such as loading errors)

  • show the results of the most recently performed operation

The call graph

Upon successfully loading an assembly program, ASM Scope analyzes control flow and displays a call graph window. The call graph is a visual representation of the subroutines defined by the program and of their caller/callee relationship. Subroutines are displayed as draggable labels; arrows connecting subroutines represent callee/caller relationships. Currently, the nodes of the graph are placed randomly in the window and you must rearrange them manually to get a more readable representation.

Commands

The command buttons are located in the control pane. These buttons either change or analyze the current selection, providing further information and offering extra context-dependent commands.

For some types of analysis, ASM Scope simulates the execution of the selection. While the selection defines a scope, it does not always define an entry point (the first line of the selection may not be the desired entry: some subroutines jump to code located physically “above” their entry points). Thus, before the analysis begins, you may be prompted to specify the entry line for the selection.

Dual shortcut buttons

Many of the analysis commands create additional navigational buttons (called dual shortcut buttons) in the control pane, as well as a Find Inside checkbox. When clicked, each button scrolls the code pane to various spots in the source code; clicking a button several times will iterate over several statements assigned to that button. Each button is mapped to two set of source code lines. The state of the Find Inside checkbox determines the set of statements currently mapped to the buttons:

  • if the Find Inside checkbox is checked, each button iterates over a set of statements inside the original selection.

  • if the Find Inside checkbox is not checked, each button iterates over a set of statements outside of the original selection.

Load button

Some releases of ASM Scope can handle multiple versions of assembly languages for multiple chip architectures. Before loading a program or parsing typed-in code, select the appropriate architecture and version from the Load button popup menu (right-click on the button to display the popup).

The Load button brings up a dialog that you can use to select a file. ASM Scope will then parse the program using the currently selected assembly language. If there are parsing errors, the status lines will display the approximate place in the input file where errors occurred. Otherwise, the interface will change to reflect the newly-loaded program and the buttons in the control pane will be activated.

Edit/Parse button

The Edit button switches the code pane from the default tree mode to editor mode; the Parse button (visible in editor mode) loads the edited text as an assembly program in the currently selected language and switches back to the default tree mode.

Selection-altering commands

When the selection changes, it is always made visible by scrolling the code pane to the appropriate location.

Back and forward buttons

The back and forward buttons (< and >) activate the previous, respectively the next selection (in browser fashion). This is useful since the selection is the most important user-program interaction channel and complex selections can be easily “lost” by inadvertent mouse clicks or by using one of the selection-altering commands.

Fold button

The Fold button creates a user-defined fold or unfolds an existing code fold. Requesting Fold when the active selection is the root of a sub-tree will unfold that sub-tree (that is, the hierarchical relationship between the former sub-tree root and its children is removed). Requesting Fold when the active selection is a contiguous list of same-level leaves will create a new fold. Other cases (trying to fold non-leaves, or noncontiguous selections, or selections that are not on the same level of the tree) currently result in undefined behavior.

Select sub button

The Select Sub button simulates execution of the program up to the first return instruction and selects all statements that would be executed. In particular, if the entry of a subroutine is currently selected, the command will select the entire body of the subroutine. Note that Select Sub does not follow CALLs; to get that behavior, right-click on the button and select Fill Sub functionality from the popup menu that appears.

Step button

The Step button quickly walks through consecutive statements. CALL or JUMP statements (conditional or not) are followed; the idea is to animate the most surprising path of execution.

Exits button

The Exits button treats the current selection as a user-defined scope, and finds all statements that cause exits from that scope. These are either boundaries of the selection (where execution “falls out” naturally) or JUMP or return statements. The selection is then updated to contain the set of exit points.

Alternate functionality is available by right-clicking on the Exits button and selecting Follow Set from the popup menu: in this case the set of out-of-scope statement where execution would continue immediately after exiting the scope is selected.

Both exits and follow-set analyses require the user to specify an entry point.

Analysis commands

These buttons analyze the current selection (without modifying it)

Calls button

The Calls button finds all subroutines called from within the current selection and adds one dual shortcut button for each subroutine:

  • if Find Inside is unchecked, the button navigates to the entry point of the corresponding subroutine.

  • if Find Inside is checked, the button cycles over all the statements in the original selection that call the corresponding subroutine.

Used regs button

The Used Regs button is currently the most sophisticated task performed by ASM Scope. It simulates execution of the selection and tracks register usage (reads/writes). Each register read from before being written to is marked as an input; each register being written to is marked as having been altered. After the simulation terminates, the inputs and outputs are displayed on two rows of dual shortcut buttons (the Inputs row and the Alters row). If the Find Inside checkbox is checked, each button cycles through either

  • for an altered register, the set of “final instances” where the register was written to. More specifically, if there are two possible execution paths that a subroutine can take before returning, and the register is modified on both paths, then both instances are recorded; however, if on the same execution path the register is modified twice (successively), then only the last instance is considered final and recorded.

  • for an input register, the set of “initial instances” where the register was read from. Again, read instances on alternate execution paths are recorded separately, but on a single path only the first read instance is considered initial and recorded.

If the Find Inside checkbox is unchecked, then ASM Scope performs a crude form of data flow analysis: for inputs, it attempts to locate the most recent write instance (which “defines” the input); for outputs, it locates the first read instance after the selection (which “uses” the output). This part of the analysis uses a crude linear search and does not take into account branches and conditions, so the results may be inaccurate.

While simulating program execution, ASM Scope caches input/output information for each subroutine encountered. This information is then made available as tooltip text for nodes in the call graph window (only subroutine inputs are displayed).

Interaction with C run-time

The output of the Used Regs analysis may reveal unwanted interactions between assembly code and the C run-time environment. ASM Scope can use colors to highlight writes to registers that may be used by the C library or by compiled C code. To turn this feature on, right-click on the Used Regs button and select the appropriate C run-time model. The next invocation of Used Regs will then highlight register buttons on the Alters row according to the following map:

  • callee-preserved registers must be saved and restored in assembly code; they are colored in yellow

  • don't touch” registers should not be modified at all or must be modified only in a specific manner (e.g. stack and frame pointers); they are highlighted in red

  • registers that are callee-preserved but may be reserved (by invoking the C compiler with a certain switch) are colored in cyan

Supported languages

ASM Scope currently handles only Analog Devices DSP assembly programs; these can be either preprocessed “legacy” assembly files (in APP format) or preprocessed VisualDSP++ files in IS format. The VisualDSP++ preprocessor is PP.EXE; to preprocess “legacy” assemly files, use asm21 -p

Known issues

This sections lists some of the current shortcomings of ASM Scope that we are aware of. If you notice other problems not listed here, please let us know so that we can make ASM Scope even better.

Annoyances

If too many buttons are generated by a Calls or Used Regs command, the buttons become illegible (the control pane should include a horizontal scrollbar). As a workaround, the button names can be identified from their tooltips. Similarly, the status lines have no scrollbar so text past the edge of the frame is truncated.

Once the call graph window is closed, it can only be re-opened by loading another program.

Incorrect or unexpected behavior

Input/output information cached when executing the Used Regs command and subsequently displayed on the call graph may be inaccurate if the initial selection does not include the entire body of a subroutine (and its descendants). This may only occur if the selection was not obtained with the Fill Sub command.

Data flow analysis does not distinguish between the primary and alternate register sets.

Limitations

Only one file can be loaded into ASM Scope. References to symbols defined in different files will not be resolved, limiting the usefulness of the tool. As a workaround, you can concatenate all the modules defining a project and create one big file; this fails, however, if there are name clashes.