For English π¬π§ scroll down or click here
Ten projekt jest mojΔ pracΔ inΕΌynierskΔ dotyczΔ cΔ napisanego w Pythonie interpretera kodu Asembly 16bit w wersji NASM. Zadaniem programu jest wspomaganie uΕΌytkownika w nauce programowania w niskopoziomowym jezyku, Asembly poprzez dostarczenie mu narzΔdzi napisanych w jezyku wysokopoziomowym umoΕΌlilwiajΔ ce analizΔ kodu z poziomu GUI i podejrzenie rezultatΓ³w w trakcie pracy programu.
- MoΕΌliwoΕΔ interpretacij poleceΕ z gotowego pliku
- MoΕΌliwoΕΔ uruchomienia programu w trybie interaktywny
- Podstawowy interfejs I/O przez symulacjΔ namiastki terminala
- MoΕΌliwoΕΔ modyfikacji wartoΕci stanu symulowanych komponentΓ³w w trybie interaktywnym
- MoΕΌliwoΕΔ powrotu do stanu sprzed wykonania polecenia
- MoΕΌliwoΕΔ automatycznego wykonywania kolejncyh polceΕ
- Podstawowe wykrywanie bΕΔdΓ³w i wyΕwietlanie potencjalnych ΕΊrΓ³deΕ problemu przy raportowaniu
Aby skorzystaΔ z programu naleΕΌy zainstalowaΔ wersjΔ interpretera Python 3.10 lub wyΕΌszΔ (projekt testowany byΕ na wersji Python 3.11).
Jak sprawdziΔ, czy poprawnie zainstalowaliΕmy Εrodowisko?
Aby upewniΔ siΔ, ΕΌe Python zostaΕ poprawnie zainstalowany, wykonaj nastΔpujΔ ce kroki w terminalu (cmd, PowerShell, Terminal, Bash β w zaleΕΌnoΕci od systemu):
- OtwΓ³rz terminal.
- Wpisz jednΔ z poniΕΌszych komend:
python βversionlub
python3 -versionPoprawna instalacja powinna zwrΓ³ciΔ numer wersji, np. Python 3.11.8.
JeΕli komenda nie zostanie rozpoznana, upewnij siΔ, ΕΌe:
- Python zostaΕ zainstalowany i dodany do zmiennej Εrodowiskowej
PATH, - na niektΓ³rych systemach (np. macOS/Linux) domyΕlnie moΕΌe byΔ wymagane uΕΌycie
python3zamiastpython.
Dodatkowo moΕΌesz uruchomiΔ interpreter interaktywny:
pythonlub
python3Po uruchomieniu powinieneΕ zobaczyΔ coΕ w rodzaju:
Python 3.11.8 (default, β¦)Aby wyjΕΔ z trybu interaktywnego, wpisz exit() lub naciΕnij Ctrl + Z (Windows) lub Ctrl + D (Linux/macOS).
π Oficjalna dokumentacja instalacji Pythona:
https://docs.python.org/3/using/index.html
Po zainstalowaniu interpretera Python i pobraniu projektu, naleΕΌy stworzyΔ Εrodowisko wirtualne dla uruchomienia projektu. WiΔcej informacji moΕΌna znaleΕΊΔ na stronie dokumentacji - dla naszego projektu, sprowadzaΔ siΔ bΔdzie to do uruchomienia poleceΕ w terminalu uruchomionego z poziomu katalogu z repozytorium:
python3.11 -m pip install venv
python3.11 -m venv my-venv-folder
source my-venv-folder/bin/activate
python3.11 -m pip install -r requirements.txtpython -m pip install venv
python -m venv my-venv-folder
my-venv-folder\Scripts\activate
python -m pip install -r requirements.txtUruchomienie i uΕΌycie programu (po poprawnej instalacji bibliotek i uruchomieniu Εrodowiska wirtualnego) sprowadza siΔ do uruchomienia programu poleceniem (zakΕadajΔ c iΕΌ jesteΕmy w katalogu projektu):
python3.11 main.pyPo uruchomieniu, powinniΕmy zobaczyΔ menu gΕΓ³wne:
W tym trybie zakΕadamy iΕΌ mamy plik, ktΓ³ry normalnie kompiluje siΔ, ale nie dziaΕa tak jak byΕmy oczekiwali. JeΕli sprΓ³bujemy uruchomiΔ plik, ktΓ³ry zawiera bΕΔdy skΕadniowe, zostanie wyΕwietlony komunikat o bΕΔdzie i pojawi siΔ opcja uruchoimenia pliku w trybie interaktywnym.
Poprawne wczytanie pliku, powinno zakoΕczyΔ siΔ ruchomieniem interpretera z podglΔ dem kodu:
Aby rozpoczΔ Δ pracΔ naleΕΌy skorzystaΔ z przycisku Uruchom program:
- Rejestry i Flagi - wskazuje wewnΔtrzy stan symulowanego ukΕadu, pozwalajΔ c zrozumieΔ podstawΔ wykonywanych operacji
- Kod - podglΔ d pliku / interetowalnego polecenia, wraz z zaznaczonΔ liniΔ , ktΓ³ra zostanie wykonana wciΕniΔciem przycisku Wykonaj instrukcjΔ
- Segment - pokazuje stan stosu procesora (dla uproszczenia, stos nie zawiera binarnej reprezentacji wykonywanego programu !)
- Zmienne - ta sekcja pozwala w Εatwy sposΓ³b podejrzeΔ wycinki stosu, w ktΓ³rych uΕΌytkowni zadeklarowaΕ zmienne
- Terminal - ta sekcja pozwala na wykonywanie podstawowej komunikacji programu z uΕΌytkownikiem przez kilka wybranych poleceΕ
Za pomocΔ przyciskΓ³w Wykonaj instrukcjΔ oraz PowrΓ³t do poprzedniej linii uΕΌytkownik zleca wykonanie nastΔpnego polecenia, lub przywrΓ³ceie stanu ukΕadu do momentu sprzed wykonania poprzedniego rozaku.
Zaznaczenie tego polecenia spowoduje automatyczneg przechodzenie przez kolejne polecenia (symulowanie naciskania przez uΕΌytkownika przycisku Wykonaj instrukcjΔ) w wybranych odstΔpach czasu oznaczonych jako OpΓ³ΕΊnienie.
Po zaΕadowaniu i wstΔpnym sprawdzeniu pliku, moΕΌliwe jest wykonywanie kolejnych polceΕ a takΕΌe powrΓ³t do stanu sprzed egzekucji polcecenia. MoΕΌliwy jest podglΔ d stanu stosu i rejestrΓ³w, co umoΕΌliwa przeΕledzenie zmian i porΓ³wnanie dziaΕania z przewidywanym sposobem wykonania programu. Po zakoΕczeniu programu, konieczne jest ponowne uruchomienie by zaΕadowaΔ ponownie kod (np. po wprowadzeniu zmian).
Podczas uruchamiania trybu interakywnego zostajemy powitani przez puste okno, gdzie naleΕΌy wprowadziΔ kod, ktΓ³ry chcemy zasymulowaΔ (wyjΔ tkiem jest otworzenie pliku, ktΓ³rego nie udaΕo siΔ uruchomiΔ w trybie Analizy - zawartoΕΔ pliku jest wtedy wczytana automatycznie):
Analiza kodu, odbywa siΔ tak samo jak w trybie analizy, z wyjΔ tkiem dwΓ³ch kwestii:
- MoΕΌliwa jest zmiana wartoΕci rejestru i stosu bezpoΕrednio w trakcie pracy programu
- Po zatrzymaniu egzekucji, moΕΌliwe jest dokonywanie zmian w kodzie programu (spowoduje to rozpoczΔcie wykonywnaia caΕego programu od poczΔ tku)
Z uwagi na rozlegΕoΕΔ tematu jakim jest interpretacja poleceΕ asemblerowych, wprowadzone zostaΕy pewne ograniczenia natury technicznej i logistycznej do programu ! Oznacza to ΕΌe nie kaΕΌdy program, napisany w Asemblerze jest moΕΌliwy do uruchomienia i interpretacji !
OgΓ³lna lista obsΕugiwanych poleceΕ widoczna jest w sekcji UkΕad plikΓ³w programu, w folderze Extras/Instructions and descriptions/. KaΕΌde obsΕugiwane polcenie, zapisane jest jako oddzielny plik .md, z nazwΔ
bΔdΔ
cΔ
obsΕugiwanym poleceniem.
Wszystkie szczegΓ³Εy nt. projektu, ograniczeΕ, implementacji i filozofii pracy programu moΕΌna znaleΕΊΔ w mojej pracy inΕΌynierskiej:
- Interpreter Asemblera 16bit - wersja Polska
- 16bit Assembly Interpreter - wersja Angielska (przetΕumaczona z pomocΔ ChatGPT)
This project is my engineering thesis which topic is an Assembly 16bit interpreter written in Python language. The goal is to provide user with help in learning low-level language like Assembly by giving tool for analysis and execution of code in high-level language with simple GUI.
- Ability to execute assembly file
- Ability to run program in interactive mode
- I/O interface in form of basic terminal
- Ability to introduce changes to the source code during execution (interactive mode)
- Ability to return to simulation state befor execution of instruction
- Ability to automatically execute instructions
- Basic error detection and display of propable sources of errors
To use this program, it's necessary to install Python interpreter version 3.10, or highier (project was develope and tested with Python 3.11).
How to check, if Python was correctly installed?
To ensure, that Pyhon was correctly installed, perform the following steps in terminal (cmd, PowerShell, Terminal, Bash - depending on the system):
- Open terminal
- Enter one of the following command
python βversionor
python3 -versionIf Python was installed correctly, current version should be returned - ex. Python 3.11.8.
If command wouldn'be be recognized, ensure that:
- Python was installed and added to environemnt variable
PATH, - on some systems (ex. macOS/Linux) by default
python3should be used, instead ofpython.
Additionally, you can run interactive mode by typing:
pythonor
python3After running command you should see something like:
Python 3.11.8 (default, β¦)To exit interactive mode, write exit() or press Ctrl + Z (Windows) or Ctrl + D (Linux/macOS).
π Official Python documentation can be found at: https://docs.python.org/3/using/index.html
After successfult instalation of Python interpreter and downloading reposity content, it's necessary to prepare virtuall environment and download libraries. More informatios about process can be found on documentaiton page - for our project everthing will come down to executing those commands in terminal from repo's folder on our machine:
python3.11 -m pip install venv
python3.11 -m venv my-venv-folder
source my-venv-folder/bin/activate
python3.11 -m pip install -r requirements.txtpython -m pip install venv
python -m venv my-venv-folder
my-venv-folder\Scripts\activate
python -m pip install -r requirements.txtRunning and using the program (after correctly installing the libraries and activating the virtual environment) boils down to launching the program with the command (assuming we are in the project directory):
python3.11 main.pyAfter launching, you should see the main menu:
Program is available in English, but screenshots depict version in Polish lanuguage
In this mode, we assume that we have a file which normally compiles but does not work as expected. If we try to run a file containing syntax errors, an error message will be displayed, and an option to run the file in interactive mode will appear.
A correct file load should result in starting the interpreter with a code preview:
To start working, use the Run program button (visible on picture as Uruchom program):
- Registers and Flags β shows the internal state of the simulated system, helping to understand the basis of performed operations
- Code β preview of the file / interactive command, with the highlighted line that will be executed when pressing the Execute Instruction button
- Segment β displays the state of the processor stack (for simplicity, the stack does not contain a binary representation of the executed program!)
- Variables β this section allows easy viewing of stack fragments where the user declared variables
- Terminal β this section enables basic communication between the program and the user through several selected commands
Using the Execute Instruction and Return to Previous Line buttons, the user commands the execution of the next instruction or restores the system state to the moment before the previous step was executed.
Checking this option will cause automatic progression through subsequent instructions (simulating the user pressing the Execute Instruction button) at selected time intervals specified as Delay.
After loading and initially checking the file, it is possible to execute further commands as well as return to the state before the command was executed. It is possible to view the state of the stack and registers, which allows tracking changes and comparing the behavior with the expected execution of the program. After the program finishes, it is necessary to restart it in order to reload the code (e.g., after making changes).
When starting interactive mode, we are greeted by a blank window where we need to enter the code we want to simulate (the exception is opening a file that could not be run in Analysis mode β in that case, the fileβs contents are loaded automatically).
Code analysis is carried out the same way as in analysis mode, with two exceptions:
- It is possible to change the values of the registers and the stack directly during program execution.
- After execution is stopped, it is possible to make changes to the program code (this will cause the entire program to restart from the beginning).
Due to the complexity of interpreting assembly instructions, certain technical and logistical limitations have been introduced into the program ! This means that not every program written in Assembly can be run or interpreted !
The general list of supported commands is visible in the section Program's files organization, in the folder Extras/Instructions and descriptions/. Each supported command is saved as a separate .md file named after the supported instruction.
All details regarding the project, limitations, implementation, and the program's operating philosophy can be found in my engineering thesis:
- Interpreter Asemblera 16bit - source file (PL)
- 16bit Assembly Interpreter - english version (translated from the original using ChatGPT)
Assembly_interpreter
ββ Example assembly programs
β ββ incorrect_programs
β β ββ engine_cant_use_sp.asm
β β ββ engine_illegal_operations.s
β β ββ engine_instruction_not_supported_error.asm
β β ββ engine_unrecognized_argument_error.asm
β β ββ engine_wrong_combination_params.asm
β β ββ engine_wrong_param_types.asm
β β ββ proc_file_empty_file_no_white_chars.asm
β β ββ proc_file_empty_file_white_chars.asm
β β ββ proc_file_file_too_big.asm
β β ββ proc_file_improper_var_name.asm
β β ββ proc_file_incorrect_file_type.txt
β ββ programs_EN
β β ββ convert_calculate_RPN.asm
β β ββ show_time.asm
β ββ programs_PL
β β ββ obliczanie_ONP_dzialania.asm
β β ββ pokaz_czas.asm
β β ββ text_val.asm
β ββ test_programs
β ββ all_vaild_add_instructions.asm
β ββ all_valid_flag_setting_instructions.asm
β ββ infinite_loop.asm
β ββ jumps_and_labels.asm
β ββ test_addition_nerar_overflow.asm
β ββ test_int21_ax10.asm
β ββ test_pushes.asm
β ββ test_variable_section.asm
β ββ working_stack.asm
ββ Extras
β ββ Instructions and descriptions
β β ββ AAA.md
β β ββ AAD.md
β β ββ AAM.md
β β ββ AAS.md
β β ββ ADC.md
β β ββ ADD.md
β β ββ AND.md
β β ββ CALL.md
β β ββ CBW.md
β β ββ CLC.md
β β ββ CLD.md
β β ββ CLI.md
β β ββ CMC.md
β β ββ CMP.md
β β ββ CWD.md
β β ββ DAA.md
β β ββ DAS.md
β β ββ DEC.md
β β ββ DIV.md
β β ββ IDIV.md
β β ββ IMUL.md
β β ββ INC.md
β β ββ INT.md
β β ββ JA.md
β β ββ JAE.md
β β ββ JB.md
β β ββ JBE.md
β β ββ JC.md
β β ββ JCXZ.md
β β ββ JE.md
β β ββ JG.md
β β ββ JGE.md
β β ββ JL.md
β β ββ JLE.md
β β ββ JMP.md
β β ββ JNA.md
β β ββ JNAE.md
β β ββ JNB.md
β β ββ JNBE.md
β β ββ JNC.md
β β ββ JNE.md
β β ββ JNG.md
β β ββ JNGE.md
β β ββ JNL.md
β β ββ JNLE.md
β β ββ JNO.md
β β ββ JNP.md
β β ββ JNS.md
β β ββ JNZ.md
β β ββ JO.md
β β ββ JP.md
β β ββ JPE.md
β β ββ JPO.md
β β ββ JS.md
β β ββ JZ.md
β β ββ LOOP.md
β β ββ LOOPE.md
β β ββ LOOPNE.md
β β ββ LOOPNZ.md
β β ββ LOOPZ.md
β β ββ MOV.md
β β ββ MUL.md
β β ββ NEG.md
β β ββ NOP.md
β β ββ NOT.md
β β ββ OR.md
β β ββ POP.md
β β ββ POPA.md
β β ββ POPF.md
β β ββ PUSH.md
β β ββ PUSHA.md
β β ββ PUSHF.md
β β ββ RCL.md
β β ββ RCR.md
β β ββ RET.md
β β ββ ROL.md
β β ββ ROR.md
β β ββ SAL.md
β β ββ SAR.md
β β ββ SBB.md
β β ββ SHL.md
β β ββ SHR.md
β β ββ STC.md
β β ββ STD.md
β β ββ STI.md
β β ββ SUB.md
β β ββ TEST.md
β β ββ XCHG.md
β β ββ XOR.md
β β ββ _ 16 bit Assembly Interpreter.pdf
β β ββ _ Interpreter Asemblera 16 bit.pdf
β ββ Utilities
β ββ flag_converter.py
β ββ show_misspelled.py
ββ README.md
ββ generate_markdow_for_supported_instructions.py
ββ main.py
ββ program_code
β ββ __init__.py
β ββ assembly_instructions
β β ββ __init__.py
β β ββ arithmetic_instrunctions.py
β β ββ bit_movement_instructions.py
β β ββ data_movement_instructions.py
β β ββ flag_setting_instructions.py
β β ββ flow_control_instructions.py
β β ββ interrupt_instructions.py
β β ββ jump_instructions.py
β β ββ logical_instrunctions.py
β β ββ stack_instructions.py
β ββ code_handler.py
β ββ configs
β β ββ color_palette.json
β β ββ names.json
β ββ custom_gui_elements.py
β ββ custom_message_boxes.py
β ββ engine.py
β ββ errors.py
β ββ flag_register.py
β ββ gui.py
β ββ hardware_memory.py
β ββ hardware_registers.py
β ββ helper_functions.py
β ββ history.py
β ββ preprocessor.py
ββ readme_pictures
β ββ interactive_mode.png
β ββ analiza_pliku.png
β ββ ekran_powitalny_gui.png
β ββ podpowiedzi.png
β ββ przyciski sterujaΜ¨ce.png
ββ requirements.txt