{"id":20994320,"url":"https://github.com/zmira/abremir.msp.simulator","last_synced_at":"2026-04-16T14:35:42.854Z","repository":{"id":197496674,"uuid":"537643165","full_name":"zmira/abremir.msp.simulator","owner":"zmira","description":"MSP (Mais Simples Possível) Simulator provides a console based IDE for the MSP assembly programming language","archived":false,"fork":false,"pushed_at":"2025-02-09T03:40:22.000Z","size":2337,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T04:17:45.616Z","etag":null,"topics":["assembly","console-application","emulator","simulator","stack-machine"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zmira.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-16T23:03:15.000Z","updated_at":"2025-01-19T02:07:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"f226f1dc-114a-4927-89d6-65b4d425d08e","html_url":"https://github.com/zmira/abremir.msp.simulator","commit_stats":null,"previous_names":["zmira/abremir.msp.simulator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmira%2Fabremir.msp.simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmira%2Fabremir.msp.simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmira%2Fabremir.msp.simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmira%2Fabremir.msp.simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zmira","download_url":"https://codeload.github.com/zmira/abremir.msp.simulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243410230,"owners_count":20286387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","console-application","emulator","simulator","stack-machine"],"created_at":"2024-11-19T07:17:44.942Z","updated_at":"2025-12-28T14:32:48.364Z","avatar_url":"https://github.com/zmira.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MSP (*Mais Simples Possível*) Simulator\n\n| ![MSP Simulator Console Application](./assets/msp-ide-console.webp) |\n|:--:|\n| *MSP (Mais Simples Possível) Simulator Console Application* |\n\n## Motivation\n\nThis started out as a \"let's see how [Superpower](https://github.com/datalust/superpower) works\" but quickly became a \"what can I use it for?\"\n\nFor that, I needed to find a small enough language, with just the right amount of complexity. I remembered that, while at [Universidade do Minho](https://www.uminho.pt/), I had used a proto-assembly language. That language was MSP! MSP stands for *Mais Simples Possível* (Portuguese for *The Simplest Possible*).\n\nI knew I had some remnants of MSP code lying around, but that wasn't enough. I remembered that we had had access to a programmer's manual that included the language's BNF grammar and the description of the instruction set. So, the search began...\n\nI looked through my backups, but to no avail. After a \"few\" web searches I managed to find something that had what I was looking for. [Deep in the pages](https://www.di.uminho.pt/~jas/pli/03-04/pli.html) of the [Departamento de Informática](https://www.di.uminho.pt/), there it was: the archive `WinMSP.tgz`, which contained what I needed.\n\nThe `WinMSP.tgz` file contains the MSP language integrated development environment (IDE) (`WINMSP.EXE`) for [Microsoft Windows](https://en.wikipedia.org/wiki/Microsoft_Windows), some examples, and both the user's manual and the programmer's manual (the one I was actually looking for) as `*.doc` files.\n\nIn order to help preserve this, I have included the downloaded `WinMSP.tgz`, as is, [in this repository](./assets/WinMSP.tgz). I have also taken the original manuals, in Portuguese, and included them in the repository as `*.pdf`: [user's manual](./assets/MSPUTMAN.pdf) and [programmer's manual](./assets/MSPLPMAN.pdf)\u003csup\u003e1\u003c/sup\u003e.\n\nThe repository's [accompanying documentation](./docs/table-of-contents.md) is a translation, from the original, of the programmer's manual, and few bits from the user's manual.\n\nWith the programmer's manual in hand, I then started developing what ended up being a console version of the original WinMSP IDE. The console application has been developed in C# and, by using [.NET Core](https://learn.microsoft.com/en-us/dotnet/core/introduction), it is cross-platform. It has been tested only in Microsoft Windows and [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)).\n\n## Internals\n\nDevelopment of the MSP Simulator was split by area of concern. This helped keep context boundaries during development and testing. The different areas of concern are briefly described below.\n\n### [Parser](./source/abremir.MSP.Parser/)\n\nThis is where it all starts!\n\nThis initial stage is where the source code is converted into an internal representation of both the data segment and the code segment, and this is done mainly by leveraging the power (pun intended) of [Superpower](https://github.com/datalust/superpower).\n\nThe internal representation generated at the end of this stage, if successful, is what will allow the following stages to be executed.\n\n### [Validator](./source/abremir.MSP.Validator/)\n\nOnce the source code has been parsed successfully, having generated internal representations of both the data initializers and the instructions, the actual values, and (potential) relationships between data and instructions, need to be validated.\n\nData and code validation are done independently, and may generate warnings and/or errors. For a full description of the warnings and errors that can be generated, please take a look at the [documentation for Errors and Warnings](docs/errors-and-warnings.md).\n\nIf the outcome of the validation does not contain any errors all is good, and the process can progress to the next stage: assembly.\n\n### [Assembler](./source/abremir.MSP.Assembler/)\n\nThe task of the assembler is to convert the internal representation of the source code into a format that the virtual machine can process.\n\nThis means the internal representation of the source code will be converted into two sets of data that represent the contents of the two memory blocks of the virtual machine: the Data Memory and the Program Memory.\n\nAside from this, the assembler will also output a map between the source code line of the code segment and its location the Program Memory, and a map between the data variables and their address in the Data Memory.\n\n### [Compiler](./source/abremir.MSP.Compiler/)\n\nThe purpose of the compiler is to wire-up everything and to prepare a payload that is ready to be served to the virtual machine. In order to accomplish this it will leverage the components already described (parser, validator, and assembler).\n\nThese components will be invoked sequentially (parser -\u003e validator -\u003e assembler) and, when completed, the compilation result will be composed of the Data Memory, the Program Memory, errors, warnings, mapping of source code line number to Program Memory address, and mapping of data address to variable identifier.\n\nIf any of the sub-stages returns errors, the process is stopped.\n\nOn a successful compilation, the resulting data memory and program memory can be fed directly to the virtual machine.\n\n### [Virtual machine](./source/abremir.MSP.VirtualMachine/)\n\nOnce fed with a compiled data memory and program memory, prepared by the compiler, the virtual machine will be able to run the program it was assigned.\n\nBesides actually executing each of the instructions that compose a program defined in the Program Memory, the virtual machine is in charge of managing internal state: `Mode`, `Status`, `Data Memory`, `Program Memory`, `Stack`, `SP`, `PC`, etc.\n\nThe virtual machine will also emit events in order to notify potential subscribers of changes happening inside the virtual machine. These range from when the virtual machine's memory is set, all the way until when the virtual machine has stopped (either intentionally or due to a program error). In fact, these events are what drives the view of the internals of the virtual machine to be updated while a program is being executed.\n\nPlease note that the current implementation of the virtual machine does not exactly match the outlined in the [architecture documentation](./doc/../docs/architecture.md), but the outcome is expected to be the same.\n\n### [Integrated Development Environment](./source/abremir.MSP.IDE.Console/)\n\nThe MSP Simulator IDE, as shown above, is a console application built using the cross-platform terminal UI toolkit [Terminal.Gui](https://github.com/gui-cs/Terminal.Gui).\n\nIts main purpose is to interact with the MSP virtual machine. In this case, this is done via the use of visual elements, which can be decomposed into 3 main areas:\n\n- a code editor window;\n- a virtual machine (VM) control and status window;\n- and input/output;\n\nThe IDE also provides an integrated help window.\n\n#### Code editor\n\n---\n\nThe code editor, where the user can type code directly or have code be loaded from file. A few [examples](./source/abremir.MSP.IDE.Console/Examples/) are included.\n\n| ![MSP code editor window](./assets/msp-ide-console-editor.png) |\n|:--:|\n| *MSP code editor window* |\n\nOnce code is loaded to the editor window it can, then, be loaded to the MSP virtual machine by clicking the `compile` button. This will trigger parsing, validation, assembling, and compiling the code to a form understandable by the VM.\n\nIf any warnings or errors are to be shown to the user, they will be so in the IDE's output window.\n\n#### Virtual machine control and status window\n\n---\n\nThrough the virtual machine control and status window the user can control how the program runs and view the internal status of the VM.\n\nThe virtual machine state panel displays the current `status` of the VM, the current running `mode`, the `instruction` currently being executed, the program counter `pc`, and the stack pointer `sp`.\n\nThe loaded compiled program can be seen in the `program memory` and `data memory` panels. The `stack` panel will display the contents of the stack as the program is executed.\n\n| ![MSP virtual machine control and status view panel](./assets/msp-ide-console-virtual-machine.png) |\n|:--:|\n| *MSP virtual machine control and status view panel* |\n\nAfter the code is loaded to the VM, it can be run in one of two modes: `run` or `step`.\n\n`run` will execute the full program without interruption, unless mandated by the code, until the program ends. This can further be controlled by adjusting the wait time between instructions `ms/instruction`. If this is set to 0 the program will run without any visible internal state updates, so it is recommended to set this value to a minimum of 1 (as seen in the [screen capture](./assets/msp-ide-console.webp) above).\n\nWhile the program is being executed in the `run` mode, the user will also have access to the `pause` button. Clicking this button will, as the name implies, pause execution.\n\nOn the other hand, `step` allows the user to control when the next instruction is executed, leaving enough time to analyze the virtual machine's internal state.\n\nThe user will also have access to a `reset` button (only while the program is being executed), which will reset the virtual machine's internals (`pc`, `sp`, `data memory`, and `stack`) to its initial state (similar to the state right after a program has been compiled and loaded to the VM).\n\n#### Input/Output\n\n---\n\nThe MSP language includes two methods to interact with the user. These are the `input` and `output` ports.\n\n| ![MSP output window](./assets/msp-ide-console-output.png) |\n|:--:|\n| *MSP output window* |\n\nThe `output` port is linked to the computer screen, in this case the IDE's output window, and this is where all warning and error messages, and programmed output will be displayed to the user.\n\n| ![MSP input modal](./assets/msp-ide-console-input.png) |\n|:--:|\n| *MSP input modal* |\n\nOn the other hand, the `input` port is linked to the computer's keyboard, in this case a modal window in the IDE, and interaction is achieved by requesting the user to enter either a number or one ASCII character.\n\n#### MSP Help\n\n---\n\nThe MSP help window (F1) provides a quick to access description of the MSP assembly programming language, with its syntax and semantics, and a list of errors and warnings that may be raised while compiling source code or running programs.\n\n| ![MSP help](./assets/msp-ide-console-help.png) |\n|:--:|\n| *MSP help window* |\n\n## Disclaimer\n\nThe source code is provided \"as-is\", use at your own risk.\n\n## Acknowledgements\n\n- `WinMsp.tgz` [Departamento de Informática da Universidade do Minho, Portugal](http://www.di.uminho.pt/~jas/Research/LRC/rpms/WinMSP.tgz) | [MSP Simulator repository copy](./assets/WinMSP.tgz)\n- [Architecture diagram for the MSP stack virtual machine](http://gec.di.uminho.pt/lcc/sc0708/proj.html)\n- José Carlos Rufino Amaro and Jorge Alexandre Santos\n- [Superpower](https://github.com/datalust/superpower)\n- [Terminal.Gui](https://github.com/gui-cs/Terminal.Gui)\n\n---\n\n[1] the original user's manual has been adjusted to include the missing diagram for the architecture of the MSP stack virtual machine, which was downloaded from [here](http://gec.di.uminho.pt/lcc/sc0708/proj.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmira%2Fabremir.msp.simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzmira%2Fabremir.msp.simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmira%2Fabremir.msp.simulator/lists"}