croesch/micro-debug

A debugger for micro-assembler-programs

Usage

micro-debug is a debugger for the Mic-1 processor invented by Andrew S. Tannenbaum, Structured Computer Organization, Fourth Edition (Prentice-Hall, 1998). You can debug the assembler code and the micro assembler code, too.

This debugger has been developed for a seminar paper. The seminar paper is stored in croesch/micro-debug-doc.

Requirements

The debugger runs on Java, so you don't need to have a specific platform. You just need at least Java 5 to run it.

Installation

This section describes how to install the debugger from released .zip-files. For developer instructions see further sections.

1. Download micro-debug-version.zip from downloads
2. Extract .zip-file
3. The debugger doesn't need installation, it is now ready to be executed, for example on linux do the following steps:
4. open command line
5. change into directory $ cd micro-debug-version/
6. execute start script $ ./micro-debug.sh --help

Basic usage

For any details you can run the debugger with the argument --help. To simply debug an assembler file using a specific micro assembler implementation, run

$ ./micro-debug.sh path-to-micro-assembler.mic1 path-to-assembler.ijvm

where the first argument is the relative or absolute path to the micro assembler byte code and the second argument is the relative or absolute path to the assembler byte code.

For specific syntax and available commands use the command HELP when the debugger is running and asking for your input (with micro-debug> ).

Also the micro processor could need some input, to determine who is requesting input from you, the processor prints the line mic1> .

Configuration

In the directory config there are several files that can be used to configure behavior of the debugger.

You can use the file micro-debug.properties to change some default values like the size of the memory or the start values of the registers.

Logger

The file logging.properties contains the configuration for the Java logger that is used when executing the debugger via start script. Please see documentation of java.util.logging for details.

ijvm.conf

Since the directory config is placed in classpath upon the debuggers jar-file, you can override files by simply adding them into the config directory. The debugger uses an ijvm.conf file to disassemble assembler code, this file is packaged in the jar-file. So if you want to use your own ijvm.conf file then just put it into the config directory and restart the debugger.

Internationalisation

The debugger uses xml-files to display any text to the user (except logging output). These files are located in the directory config/lang/.

The debugger scans four files when you are running it:

1. text_lang_CT_var1.xml, where lang is the language, CT the country code and var1 the variant, all provided by the default locale of your JVM. This file is read first (if it exists). Any keys not found in this file will be searched in the following three files.
2. text_lang_CT.xml
3. text_lang.xml
4. text.xml, the basic file for internationalisation. If any key is not found in a specific file or the files don't exist, than it will be searched in this file. So it is an important basis.

If you want to translate (or add translation to the debugger), just add the files named as shown above to the directory config/lang/ and restart the debugger. It should automatically use the new files, if they are more specific (regarding to the list above) than the existing ones and contain language, country and variation of the used locale.

If you find a mistake in existing translation or translate the existing files to your language, please let us know and it would be a pleasure to add your contribution to the project!

Contribution

Although this project has been developed in a seminar paper it is now open for your contributions. There are several ways how you can contribute:

• you can translate the translation files to your language (as described above)
• you can test the debugger and open some bugs and/or feature requests in the issue tracking system
• you can fix a bug and contribute your changes
• you can just let us know that you're using the debugger and describe your experience using it

Issue tracking

You have found a bug? Or have any suggestions how to improve the debugger? Then please create an issue here on GitHub!

https://github.com/croesch/micro-debug/issues

Development

Once you forked the repository and checked out a local copy you can use maven to build the project and run the tests:

• $ mvn clean package to compile, test and package the project
• $ mvn test to compile and run the tests

You can now change behavior add tests and test your changes. After you successfully developed on a feature, you can push your changes to your public repository and make a pull request.

Please develop in feature branches! Please see help on GitHub for how to do that.

Copyright and licensing

Copyright © 2011-2012 Christian Rösch; Copyright © 1999 Prentice-Hall, Inc.

Authors

Christian Rösch

• https://github.com/croesch
• christianroesch:: at ::gmx.net

Ray Ontko

• http://www.ontko.com/~rayo/
• rayo:: at ::ontko.com

License

License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

micro-debug's Issues

Implement command to skip over/out (of) a macro code method

The user should have the possibility to skip over or out of a method in the micro code.

Argument#OUTPUT_FILE doesn't close opened stream

The opened file stream is never closed. So add a method like clearReferences() to Argument so that each instance can clean up before end of the program.

Implement possibility to cancel run-command, when processor ran into loop

At least when you are running a program the user should have the opportunity to cancel running the program and step back into the debugger's menu again. Currently this is not possible and the user has to quit the debugger if the program ran into a loop.

So at least when running (maybe stepping) through the micro/macro code the user should have the opportunity to cancel the running command, the only way this might be possible, might be with another thread.

Another possibility would be to give a configuration entry that says how many ticks can be done at maximum. So that if the processor runs into a loop it executes just the maximum of ticks and the user has access again.

Add possibility to remove all breakpoints

It would be much easier for a user to remove all breakpoints at once instead of every single on after another.

Document the placeholders in XML files

The placeholders in XML files should be documented.

Also it would be good to have some basic information about the keys and their meaning.

Mark inherited JavaDoc comments

Remove inherited JavaDoc comments and replace them with {@inheritDoc}.

Fix classpath problem in start scripts

The start scripts define the jar-file before config directory in the classpath.

That makes it impossible to change the ijvm.conf while using the start script. Set config directory upon jar-file in classpath.

Add possibility to deactivate breakpoints

It would be nice to be able to deactivate breakpoints for a single run and to activate them again. One should be able to deactivate one single breakpoint and all breakpoints.

Parameter.NUMBER change format

Improve the format of numbers being read. Instead of 10_123123 use 123123_10.

Also extend the formats to accept, add 0o as prefix for octal values and 0b as prefix for dual values.

Settings - provide default values

The Settings should contain default values, so if the user deletes a key or later if the user uses an old configuration no problem occurs.

IJVMCommandArgument.LABEL - improve representation

For a better experience the LABEL should print the address to which it points.

Currently nice to have would be, to pre-process the code and print real labels.

Remove CRITICAL warnings

Currently there are over 20 CRITICAL warnings when running sonar, which is unacceptable. Remove them..

Remove JavaDoc warnings

Remove the following warnings:

[WARNING] SignalSet.java:49: warning - Tag @see: can't find Mic1SignalSet(int) in com.github.croesch.micro_debug.mic1.controlstore.SignalSet
[WARNING] MicroInstruction.java:199: warning - Tag @link: reference not found: Mic1BBusRegister
[WARNING] TraceManager.java:41: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.Mic1
[WARNING] Settings.java:62: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.mem.Memory
[WARNING] Settings.java:37: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#CPP
[WARNING] Settings.java:39: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#H
[WARNING] Settings.java:41: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#LV
[WARNING] Settings.java:43: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MAR
[WARNING] Settings.java:45: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MBR
[WARNING] Settings.java:47: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MDR
[WARNING] Settings.java:49: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#OPC
[WARNING] Settings.java:51: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#PC
[WARNING] Settings.java:53: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#SP
[WARNING] Settings.java:55: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#TOS
[WARNING] Settings.java:37: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#CPP
[WARNING] Settings.java:39: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#H
[WARNING] Settings.java:41: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#LV
[WARNING] Settings.java:43: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MAR
[WARNING] Settings.java:45: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MBR
[WARNING] Settings.java:47: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#MDR
[WARNING] Settings.java:49: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#OPC
[WARNING] Settings.java:51: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#PC
[WARNING] Settings.java:53: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#SP
[WARNING] Settings.java:55: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.register.Register#TOS
[WARNING] Settings.java:62: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.mem.Memory
[WARNING] TraceManager.java:41: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.Mic1
[WARNING] TraceManager.java:41: warning - Tag @link: reference not found: com.github.croesch.micro_debug.micro_debug.mic1.Mic1

Improve implementation of Memory

The implementation of the class Memory is in some cases not optimal. So there are some steps to improve it:

• improve the comments of some methods, especially readBlock(int, int, InputStream)
• poke() does not communicate its functionality, so tick() would be better
• split the class in the memory itself and something that uses it for debugging issues (at least all print.. methods)

Implement breakpoint for registers without value

It should be possible to set a breakpoint for a register. So that the debugger halts before the register is written with a new value.

Argument.ERROR_UNKNOWN show help

For better user experience the help should be shown if the user uses an unknown argument.

Remove IDIV from ijvm.conf

Normally the micro assembler doesn't contain IDIV, so remove it from ijvm.conf.

Improve assembler code output - multiple NOPs

The output of the assembler code can contain multiple NOPs. This could be filtered.

So that
NOP NOP NOP NOP

becomes

NOP .. NOP

Exception when executing LS-MACRO-CODE

The following exception occurs when executing ls-macro-code with the files values.ijvm and selectionsort.mic1 from Micsi.

Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: -1
       at com.github.croesch.micro_debug.mic1.mem.Memory.getByte(Memory.java:322)
       at com.github.croesch.micro_debug.console.MemoryInterpreter.refineEndOfCode(MemoryInterpreter.java:250)
       at com.github.croesch.micro_debug.console.MemoryInterpreter.getLastPossibleCodeAddress(MemoryInterpreter.java:234)
       at com.github.croesch.micro_debug.commons.AbstractCodeContainer.printCode(AbstractCodeContainer.java:60)
       at com.github.croesch.micro_debug.commons.AbstractCodeContainer.printCode(AbstractCodeContainer.java:36)
       at com.github.croesch.micro_debug.console.Mic1Interpreter.printMacroCode(Mic1Interpreter.java:250)
       at com.github.croesch.micro_debug.console.UserInstruction$5.execute(UserInstruction.java:92)
       at com.github.croesch.micro_debug.console.Debugger.run(Debugger.java:65)
       at com.github.croesch.micro_debug.MicroDebug.handleEnoughArguments(MicroDebug.java:114)
       at com.github.croesch.micro_debug.MicroDebug.main(MicroDebug.java:73)

Extend Exceptions to distinguish between error in micro code and macro code

It would be nice to have two exceptions indicating the file type (micro / macro) that wasn't valid.

With that information especially a GUI could offer a much better experience for the user.

Write a tutorial

It is necessary to have a tutorial how to use the debugger. It should contain:

• Find a bug in micro code
• Find a bug in macro code
• How to configure micro-debug
• How to change texts / add translation

Add it to wiki on github and add a file in the project ..

IINC second argument is shown as zero

The following code

iinc c -48

is currently disassembled to that:

0xE: [ 0x84] IINC  0 0x0

Create opportunity to skip micro/macro breakpoints

When running the application being debugged, the user should have the possibility to run (without noticing micro/macro breakpoints).

For this functionality, register breakpoints should be seen as micro breakpoints and local variable breakpoints as breakpoints for macro behavior.

RESET should also reset Input/Output

RESET currently doesn't reset the buffer of in and output. That is really confusing and should be fixed!

Split class Parameter

The class Parameter is also used when it is not logically used as a Parameter. So extract the behavior of the class into own classes and use the new classes where Parameter is logically incorrect.

Print traced register only when value changes

The instruction trace-reg and untrace-reg are used to trace a register. Tracing a register should result in printing the value of the register on every change of its value.

Add methods for BreakpointManager for removing breakpoints

For testing purpose and use of a GUI it is necessary to have methods to remove breakpoints like adding them.

Splitt class Mic1

The class Mic1 is really big and it has a lot of methods that don't belong to each other logically. So it would be good to move some methods in their own type, especially the delegating methods.
For that it should be useful to have a proper interface, that can be used by the GUI in future, too.

Implement command to skip over/out (of) a micro code method

The user should have the possibility to skip over or out of a method in the micro code.

LS-STACK don't show value at initial SP value

Currently stack listing results in showing also the value at the initial SP address. But that normally doesn't make sense.
So either start with the address after the initial SP or add an entry to configuration file, so that one could enable it again.

Recognize methods in assembler code

Think about a possibility to recognize methods in assembler code and print it to user, for example one could recognize the following code ireturn nop ... nop ... or halt nop ... nop ....
Also one could check possible candidates for methods with the first values in the constant pool.

Remove JavaDoc warnings

[WARNING] Javadoc Warnings
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:62: warning - Tag @see: can't find Argument(int) in com.github.croesch.micro_debug.argument.AArgument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:81: warning - Tag @see: can't find Argument() in com.github.croesch.micro_debug.argument.AArgument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:96: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @see: reference not found: Argument#matches(String)
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:143: warning - Tag @link: reference not found: Argument
[WARNING] /home/dafo/workspaceI/micro-debug/src/main/java/com/github/croesch/micro_debug/argument/AArgument.java:124: warning - Tag @link: reference not found: Argument

Script is only executable from same directory

There are two scripts, one for linux and one for windows. Unfortunately you can only start the application if you are in the same directory as the start scripts and the program files.

For a better user experience the script should be possible invoked from everywhere and the classpath should set correctly.

If no better solution appears, the user has to set a variable on installation, where the program files are lying.

Improve naming

There are some improvements of the naming in the code:

• the package com.github.croesch.misc should be renamed to something more common: util or commons
• the classes in the package com.github.croesch.mic1.controlstore have all the prefix Mic1, that is not good, so remove it, where it is not necessary
• the class Mic1Instruction should be renamed to MicroInstruction. So then if we would have a own type for macro instructions it could be named MacroInstruction, regarding to #9

Improve console output of debugger

Escpecially when the debugger is requesting input it is not clear what the user should enter. So extend the information the debugger prints to console, at least when something is read from the user.

REFACTOR: Extract macro instruction as own type

Currently the handling of macro instructions is not as good as it could be. For the code quality it would be good to have an own type for the instruction.. that would improve its structure and the readability.

Hide Delegate

There are a lot of chains like getClass().getClassLoader() and even much longer. Try to remove them and reduce the dependencies.

FileFormatException: hide details

When starting the debugger it would be useful for the user to see a suggestion how to fix the problem. Details about the problem can be logged.

Improve resource management

Currently there are some resources (properties files and xml-files) that are read in enums. This should be improved, extract the reading facility into an own class and separate it from the enums, so that a GUI implementation can use the reading facilities..