A 3rd year dissertation project by Lawrence Warren for Dr. Steven Bagley of The University of Nottingham.
- What is KoMo2? A brief history
- Installation
- Dependencies
- User Manual
- Binaries
- Shell Scripts
- Contributing to KoMo2
- Technical Documentation
1st year students at The University of Nottingham are taught a compulsory module, Systems and Architecture (SYS), which teaches them the fundamentals of a CPU architecture such as registers, memory, and assembly instructions. To do this, students are tasked with writing their own basic ARM assembly programs and running them in a program called KoMoDo.
KoMoDo is an ARM emulator application which uses a GUI to display the values within the memory and registers of an emulated ARM computer system.
KoMoDo provides buttons to control the operation of the emulated system. For instance, there are button to:
- Perform a single FDE cycle.
- Begin an indefinite FDE loop.
- Pause an indefinite FDE loop.
- Refresh the system (reload the program, set Program Counter to 0)
It also allows for the setting of breakpoints, which will interrupt an indefinite FDE loop if the Program Counter steps into the address where the breakpoint is set.
However, KoMoDo is becoming outdated. The purpose of the KoMo2 project is to provide necessary updates to the applications UI, logic, dependencies, and accessibility, while maintaining KoMoDo's functionality and ease of use.
In short, KoMo2 is a Linux GUI application that allows for both the inspection and control of the state of an emulated ARM computer system, which can load and run user written ARM assembly programs.
- Install the required tools described in the subsection Toolchain.
- Install the required libraries described in the subsection Libraries.
- Clone this repository.
- Enter the root directory of this project.
- Run the
makecommand to execute the provided makefile. - Optional - Execute any scripts found in the
scriptsdirectory. Information can be found in the subsection Shell scripts. - Run the newly generated
kmdbinary in thebindirectory.
To build this program from source, you must have a C and a C++ compiler. The makefile assumes that GCC is installed, and uses the commands g++ and gcc.
Furthermore, to execute the makefile, you must have GNU Make installed, giving you access to the command make.
KoMo2 is implemented using GTKMM, a C++ implementation of the popular GUI library GTK+. GTKMM in turn has many of it's own dependencies - a full list can be found here.
These libraries are popular and compiled versions can likely be found on your Linux distributions package manager. For instance, in the following distributions you can execute the following commands:
Debian, Gentoo, SuSE & Ubuntu:
apt-get install libgtkmm-3.0-dev
Fedora, RedHat & CentOS:
yum install gtkmm30-docs
Alternatively, it is possible to compile them from source - instructions are readily available online - but this can be finicky and requires assembling your own toolchain.
Below is a clear description on how to utilise KoMo2.
You must write your own ARM assembly programs (.s file extension) in an external text editor, and save them on your filesystem.
In the top right corner of KoMo2 there is a button labelled "Select File", which will open a file browser that allows you to select any .s file on your system.
Once a file is selected, press the button labelled "Compile & Load", which will create a compiled .kmd file in the same directory as your .s file, and will automatically load this into the ARM emulator.
The "Select File" and "Compile & Load" buttons are only accessible while KoMo2 is in certain states, and can be executed using the shortcuts Ctrl+L and CTRL+R respectively.
Once a program has been compiled and loaded into the ARM emulator, execution of the program can commence.
There is a button on the bar at the top of the screen which displays a green play symbol. Upon clicking this button, the program loaded will begin executing and the button will toggle to display a blue pause symbol. Upon pressing again, the program loaded will pauses execution and the button will toggle back to a green play symbol.
The state of the button will change upon every click, alternating between pausing and playing, and the operation it performs will change similarly between commencing, pausing, and resuming execution of the emulator.
The commence, pause, and play buttons are only accessible when KoMo2 is in certain states, and can be executed using the shortcut F5.
There is a button on the bar at the top of the screen which displays an arcing blue arrow. Upon pressing this button, the ARM emulator will perform perform a single step of execution - whatever instruction is at the memory address indicated by the value in the Program Counter register will be executed - and then stop.
The single step execution button is only accessible when KoMo2 is in certain states, and can be executed using the shortcut F6.
There is a button on the bar at the top of the screen which displays a hollow red square. Upon pressing this button, the ARM emulator will be set to a halted state - execution will stop, and will not be allowed to be resumed again, unless the program is recompiled and loaded.
The halt execution button is only accessible when KoMo2 is in certain states, and can be executed using the shortcut F1.
There is a button on the bar at the top of the screen which displays a blue arrow pointing to it's own tail in a circular shape. Upon pressing this button, the ARM emulator will reset itself - execution will stop and the Program Counter will return to 0, meaning that execution will begin again as if the program was running for the first time.
The reload program button is only accessible when KoMo2 is in certain states, and can be executed using the shortcut Ctrl+R.
Below is a clear description of the remaining KoMo2 GUI elements, and what each of them represents and does.
There is a table of 16 rows and 2 columns on the left hand side of the KoMo2 GUI. This table displays all of the ARM emulator's CPU registers, and the values within them.
The first 15 labels in the table - labelled R0 through R14 - are the values within the general purpose registers of the CPU.
The final register - labelled PC - is the Program Counter, which contains the memory address of the next instruction to execute. For each cycle of the ARM CPU, this will change (it will usually increase linearly, but may jump up or down values if meeting one of the branch instructions)
If the address within the PC is currently visible in the memory window, it will be highlighted in the memory window.
As the CPU runs, the values within all of these registers may change depending on how your program utilises them.
The large scrolling window that takes up the majority of the KoMo2 GUI is the memory window - this displays what is loaded into the ARM emulator's memory at each given address.
You can scroll up and down this window to view a wide range of memory addresses - the ARM emulators address bus is 32-bit.
As you look at the memory window, you can see red buttons on each row. These buttons can be toggled on or off to set breakpoints within the ARM emulator, which will pause execution of the program if the Program Counter reaches that memory address.
Furthermore, the address stored in the Program Counter is highlighted in yellow in the memory window if it in view.
As KoMo2 performs actions, it may log some outputs. These outputs are viewable in the terminal, which takes up the majority of the bottom of the KoMo2 GUI. The contents of the terminal can be cleared through a nearby button labelled "Clear".
If you write a program which requests input, you may utilise the singular input box below the terminal window to provide this input. Text will not show in the input box - rather it is immediately captured and sent to ARM emulator, which will process the input and display some output into the terminal window in response.
As part of ensuring KoMo2 is accessible for all who use it, the Accessibility ToolKit (ATK) API has been implemented within the program to allow for screen reader compatibility.
If you are using a compatible screen reader - KoMo2's screen reader implementation was tested with the Orca screen reader - information will be read out as you navigate over GUI elements. For example, if you navigate over a memory row, it will state what address it is, what is stored at that address, and if a breakpoint is set, if you navigate over a button, it will tell you what button is in focus, etcetera.
For reading the register values, which are not keyboard navigable, press the Alt key + 0-9, A-E to read the relevant register values. For example, Alt+0 reads the value stored in R0, Alt+8 reads the value in R8, Alt+A reads the value in R10, and Alt+E reads the value in R14.
For reading the Program Counter, press Alt+P.
Furthermore, pressing Alt+M toggles how the memory window mnemonics are read out. By default, the ARM instructions in the memory window are read it as they are displayed on the screen. However, this may not be the best way to communicate this information sonically. Toggling the mnemonics mode allows for the mnemonics to be read out in plain English - they are not converted in how they are displayed in the GUI.
KoMo2 includes a makefile in its root which generates 3 binaries in the bin directory. It is always assumed that these 3 binaries exist in the same directory, alongside an additional plaintext file:
kmd is the executable for the KoMo2 program proper.
Running this binary will launch the GUI, and the following 2 binaries will be forked from it when necessary.
The source files for this binary can be found in the directory src/kmdSrc/.
jimulator is the executable for the ARM emulation program Jimulator, for which KoMo2 is a front end.
This binary is forked at the very beginning of kmd's main function, and the two processes should always run in parallel.
The source files for this binary can be found in src/jimulatorSrc/.
aasm is the executable for an arm assembler program, which takes an input .s ARM source file and compiles it into a proprietary Jimulator readable .kmd file, which can be loaded into the jimulator binary.
This binary is forked upon pressing the "compile & load button" present in the GUI, and runs briefly until the output .kmd file is generated.
The source files for this executable can be found in src/aasmSrc/, and compilation is performed in the make file.
mnemonics is a plain text file on which aasm is dependant. It is always assumed that mnemonics is in the same directory as the aasm binary.
A shell script is provided with KoMo2 that allow for an enhanced user experience.
The shell script installFonts.sh has been included in the project scripts directory.
KoMo2 uses a mono space font family known as Fira Code, and this shell script installs these from an archive file tracked in the res/ directory.
If you enter the scripts/ directory and execute the shell script as root (sudo ./installFonts.sh) then these fonts will be installed for you automatically.
WARNING, it is worth bearing in mind that the shell script provided is based on one found in this Medium article, and it require root privileges as it does access the protected directory usr/local/share/fonts, so inspect the shell script and linked article first and make up your mind about if you want to run it.
I have ensured that all fonts used can always fall back to the default "monospace" font option should you not want to install the Fira Code font.
Contributing to KoMo2 is easy! If you identify a flaw with the program, or have an idea for a feature request, you are invited to attempt to implement it yourself on a fork of the existing repository, or open an issue on the GitHub to discuss it further.
Some guidance below is provided on how to get started.
Exactly what text editor or IDE is used for development is up to developer preference, but there are several tools that have been used in initial development of KoMo2 to increase code readability and quality:
-
ClangFormat is a C and C++ formatter that can be run on a source program to create a consistent, human-readable file, and leaves you not having to worry about styling. More information can be found here.
This program has been developed using the default settings for ClangFormat, however you can configure a custom formatter file if you desire.
-
Doxygen is a tool that allows for generation of documentation on classes, variables and functions from specially styled comments embedded in the code. Many doxygen comments can be found in the code base, but an example of a basic Doxygen comment is as follows:
/** * @brief A function which takes a base value and a power, and returns the * base to that power. For example, `baseToThePower(2, 2)` returns `4`, * `baseToThePower(2, 3)` returns `8`. * @param base The base that will be put to the power. * @param power The power to raise the base by. * @returns int - the resulting value of the base to the power. */ int baseToThePower(int base, int power) { if(!power) { return 1; } return base * baseToThePower(base, power - 1); }
More information about Doxygen can be found here.
It is recommended that any new files, classes, functions or member variables that are added to the codebase have a full Doxygen comment provided with them. No specific rules about how to write these comments are in place, but ensure they are clear on what the file, class, function or member variable is for.
The motivation for the dissertation project which spawned the KoMo2 was as follows:
"...there is a need for an updated and improved Jimulator GUI which is more up to date, better designed, more maintainable, and more accessible to a diverse set of users."
While this project does represent an improvement on KoMoDo, there are still some features that could improve within KoMo2 that were outside the scope of this project.
Some possible areas for improvement are as follows:
- The source code for the
bin/aasmbinary, (found insrc/aasmSrc/) is a mess. It could do with some serious revisions or at least some documentation. - The source code for the
bin/jimulatorbinary (found insrc/jimulatorSrc/) is a mess. It could do with some serious revisions or at least some documentation. - Currently, the
aasmandjimulatorbinaries are forked from the program as separate processes, and communicated with through pipes. This presents some issues, such as a particularly old school piping API that primarily works through messages sent as binary representations of data. Moving the source for these programs into the Jimulator executable and launching them as separate threads would allow for far clearer and easier communication between KoMo2 and it's child modules. This would also have the additional benefit of (potentially) allowing for cross platform compilation of the program onto Windows and MacOS. - The graphics library GTKMM is going to be receiving it's 4.0 revision in the coming months (as of April 2021). For future proofing, it may be worth experimenting with and implementing any new features that GTKMM-4 provides, and ensuring that KoMo2 does not rely on any features being deprecated by this revision.
- Web technologies, such as Javascript, CSS, and HTML, are becoming the norm for GUI programming. There are ways to interface C++ with these web technologies which could allow for a more dynamic and agile GUI development experience.
If you do make any improvements or additions to KoMo2, please open a pull request on the GitHub repository. I will happily discuss and review your changes, and merge them into the trunk if they are suitable. 🎉
For technical documentation of KoMo2 generated by Doxygen, Click here.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent