﻿Asmonite 0.5.0
==================

Copyright © 2026 Nils Belde - https://asmonite.com
Freeware, see LICENSE.txt.
Discord (Fragen, Fehler, Ideen / questions, bugs, ideas): https://discord.gg/Sj8kvqEkc

The English text follows the German one.


DEUTSCH
-------

Inhalt
  Asmonite.exe      Editor, Assembler und Debugger (i386, x64, ARM Thumb-2,
                    ARM64; Windows und DOS)
  Dismonite.exe     Disassembler und Debugger für Windows- (PE: x86, x64, ARM,
                    ARM64), DOS- (MZ) und ARM-Linux-Programme (ELF)
  asmoc.exe         der Assembler auf der Kommandozeile: asmoc datei.asm
  conwatch.exe      Hilfsprogramm des Debuggers (zeigt die Ausgabe des Programms
                    im Ausgabefenster); muss neben Asmonite.exe liegen
  dbgload.com       Hilfsprogramm zum Debuggen von DOS-Programmen
  examples\windows_*  Beispielprogramme für Asmonite (demo.asm, hello.asm)
  help\             die Texte der Befehlsinfo (F1) in Deutsch und Englisch; muss
                    neben den Programmen liegen bleiben
  examples\dos\     hello_com.asm und hello_exe.asm: Hello World für DOS als .COM
                    und als .EXE, mit Erklärung des Unterschieds (Asmonite, F9);
                    HELLO.EXE für Dismonite (zählt hoch, eine Zahl pro Zeile),
                    der Quelltext HELLO.PAS (Turbo Pascal)
  examples\winarm\  pe_arm32_hello_world.exe für Dismonite: ein Programm für
                    Windows on ARM (ARM32/Thumb-2), schreibt "Hello World!";
                    der Quelltext .asm (asmoc baut es Byte für Byte)
  examples\x64\     hello64.asm: ein x64-Programm (.arch x64, .format pe),
                    das Windows ausführt; mit F9 in Asmonite debuggen
  examples\arm64\   a64asm_hello.asm: dasselbe für ARM64 (.arch arm64), für
                    einen Windows-on-ARM64-Rechner (Debug-Ziel einrichten)
  qemu\run_buster.bat  Raspberry Pi OS (ARM) in QEMU, zum Debuggen von
                    ARM-Programmen mit Dismonite (siehe unten)
  qemu\run_freedos.bat FreeDOS in QEMU; lädt die FreeDOS-Diskette, die
                    Asmonite und Dismonite für DOS-Programme brauchen
  debugserver\asmodbg.exe  Debug-Server für den Windows-on-ARM-Rechner (siehe unten)
  debugserver\asmodbg64.exe  dasselbe für ARM64-Programme (läuft auf Windows on ARM64)
  debugserver\asmodbgx64.exe  Debug-Server für x64-Programme auf diesem Rechner
  LICENSE.txt       die Lizenz
  CHANGELOG.md      was sich geändert hat

Erste Schritte
  1. Den Ordner an einen beliebigen Ort entpacken, eine Installation gibt es nicht.
  2. Asmonite.exe starten und examples\windows_intel\demo.asm öffnen.
  3. Strg+F9 assembliert, F9 startet das Programm im Debugger,
     F5 setzt einen Haltepunkt, F8/F7 gehen Schritt für Schritt.

Hinweis: Die Programme sind nicht signiert. Windows fragt deshalb beim ersten
Start eventuell nach ("Der Computer wurde durch Windows geschützt" -> "Weitere
Informationen" -> "Trotzdem ausführen").

Zum Debuggen von DOS-Programmen brauchen Asmonite und Dismonite QEMU
(https://www.qemu.org) und eine FreeDOS-Diskette (https://www.freedos.org).
Einmal qemu\run_freedos.bat starten: es lädt die Diskette (720 KB, nach
Rückfrage) nach qemu\freedos\freedos.img und bietet, falls QEMU fehlt, die
Installation an (winget; auf Windows on ARM die native ARM64-Version von
qemu.weilnetz.de). Asmonite und Dismonite finden die Diskette dort.
Zum Ausprobieren: examples\dos\HELLO.EXE in Dismonite öffnen, F7 startet QEMU
und hält am Einsprungpunkt.

ARM-Programme (Linux, ELF) debuggt Dismonite in Raspberry Pi OS unter QEMU:
qemu\run_buster.bat starten. Beim ersten Start lädt es die fehlenden Dateien
(etwa 440 MB, nach Rückfrage) und richtet das System ein (einige Minuten,
braucht Internet); fehlt QEMU, bietet es die Installation an (wie oben).
"run_buster -h" zeigt die Optionen. Anmeldung: pi / raspberry.

ARM-Programme für Windows on ARM (PE, Machine 0x1C4) debuggt Dismonite auf einem
echten Windows-on-ARM-Rechner. Einrichtung beim ersten Mal (zwei Rechner):
 1. Auf dem ARM-Rechner, in einer normalen Eingabeaufforderung (nicht als Administrator):
      powershell -NoProfile -Command "irm https://asmonite.com/downloads/install-asmodbg.ps1 | iex"
    Die Zeile lädt asmodbg.exe nach C:\Users\<name>\asmodbg, prüft die Prüfsumme und
    startet den Server (eine ältere Version wird ersetzt). Dismonite zeigt die Zeile
    zum Kopieren im Dialog "Debug-Ziel Windows on ARM". Ohne Internet: debugserver\asmodbg.exe
    von Hand in einen eigenen Ordner kopieren und per Doppelklick starten, NICHT als
    Administrator. Windows warnt eventuell (nicht signiert, "Weitere
    Informationen" -> "Trotzdem ausführen"). Es öffnet sich ein kleines Fenster
    (im Kompatibilitätsmodus, die Schrift kann unscharf sein): "... in Ordnung",
    die IP-Adressen, der Port (23457), der Code (XXXX-XXXX-XXXX) und der Status.
    Das Fenster muss offen bleiben, solange man debuggt. Der Rechner darf dabei
    nicht in den Energiesparmodus gehen (sonst kommt in Dismonite nur "Keine
    Verbindung"): am Netzteil betreiben und einmal in einer Eingabeaufforderung
      powercfg /change standby-timeout-ac 0
      powercfg /change monitor-timeout-ac 0
    eingeben (bei ARM-Laptops kann schon das Abschalten des Bildschirms den
    Energiesparmodus auslösen).
 2. Firewall: Windows fragt beim ersten Start am Bildschirm des ARM-Rechners, ob
    asmodbg ins Netz darf. Dort "Zulassen" bestätigen (auch für das Netz, in dem
    der Rechner ist; WLAN gilt oft als "öffentlich"). Wurde das verpasst, einmal
    in einer Eingabeaufforderung als Administrator (Pfad anpassen):
      netsh advfirewall firewall add rule name=asmodbg dir=in action=allow
        program="C:\Users\<name>\asmodbg\asmodbg.exe" protocol=TCP
        localport=23457 remoteip=localsubnet profile=any
    und dieselbe Zeile noch einmal mit protocol=UDP (für "Search LAN" in Dismonite).
    Die Regeln erlauben nur Rechner im selben lokalen Netz.
 3. Auf dem Entwicklungsrechner: ein ARM-PE-Programm in Dismonite öffnen (zum
    Ausprobieren examples\winarm\pe_arm32_hello_world.exe) und F9
    (oder F7/F8) drücken. Weil noch kein Ziel eingerichtet ist, öffnet sich
    "Debug-Ziel Windows on ARM" (auch jederzeit unter Debug). "Direkt" wählen,
    "Search LAN" drücken (findet den laufenden asmodbg im Netz und trägt Adresse
    und Port ein; sonst beides aus dem Fenster abtippen), den Code eintragen und
    "Test connection" drücken. Meldet der Test "OK", mit OK speichern: Dismonite
    lädt das Programm hoch, startet es dort und hält am Einsprungpunkt.
    Die Programmausgabe erscheint im Ausgabefenster.
 Hinweise: Der Code schützt den Server (Anmeldung und Prüfsumme jedes Pakets,
 keine Verschlüsselung); er liegt mit DPAPI geschützt neben asmodbg.exe, "asmodbg
 --new-code" erzeugt einen neuen. asmodbg.exe und Dismonite müssen dieselbe
 Version haben (der Test sagt es); den Server kopiert man dann von Hand neu. Nur
 in einem Netz benutzen, dem man traut: das Programm läuft dort wirklich.
 Alternativ ohne asmodbg-Fenster: "ssh"-Ziel (Schlüssel-Anmeldung zum Rechner
 nötig; Dismonite kopiert den Server selbst).

ARM64-Programme (PE, Machine 0xAA64) gehen genauso, aber mit dem Server
debugserver\asmodbg64.exe auf dem Windows-on-ARM64-Rechner: kopieren und starten
wie asmodbg.exe (Doppelklick, nicht als Administrator; der Dialog "Debug-Ziel
Windows on ARM" ist derselbe, auch "ssh" kopiert ihn selbst). Beide Server nehmen
im Direktmodus Port 23457: es läuft immer nur einer; für beide gleichzeitig
bekommt einer mit "--port" einen anderen, dieselbe Zahl steht dann in Dismonite.
In der Windows-Firewall braucht asmodbg64.exe seine eigene Regel (wie oben, mit
dem Pfad von asmodbg64.exe).

x64-Programme (PE, Machine 0x8664) debuggt Dismonite auf dem eigenen Rechner:
ein 32-Bit-Programm kann einen 64-Bit-Prozess nicht debuggen, deshalb startet
Dismonite debugserver\asmodbgx64.exe selbst als Kindprozess (kein Anmeldecode,
keine Firewall-Regel, nur die Loopback-Adresse). F9/F8/F7 wie sonst.


ENGLISH
-------

Contents
  Asmonite.exe      editor, assembler and debugger (i386, x64, ARM Thumb-2,
                    ARM64; Windows and DOS)
  Dismonite.exe     disassembler and debugger for Windows (PE: x86, x64, ARM,
                    ARM64), DOS (MZ) and ARM Linux (ELF) programs
  asmoc.exe         the assembler on the command line: asmoc file.asm
  conwatch.exe      helper of the debugger (shows the output of the program in
                    the output window); must be next to Asmonite.exe
  dbgload.com       helper for debugging DOS programs
  examples\windows_*  example programs for Asmonite (demo.asm, hello.asm)
  help\             the texts of the instruction info (F1) in German and English;
                    must stay next to the programs
  examples\dos\     hello_com.asm and hello_exe.asm: Hello World for DOS as .COM
                    and as .EXE, with an explanation of the difference (Asmonite,
                    F9); HELLO.EXE for Dismonite (counts up, one number per line),
                    its source HELLO.PAS (Turbo Pascal)
  examples\winarm\  pe_arm32_hello_world.exe for Dismonite: a program for
                    Windows on ARM (ARM32/Thumb-2), writes "Hello World!";
                    its source .asm (asmoc builds it byte for byte)
  examples\x64\     hello64.asm: an x64 program (.arch x64, .format pe) that
                    Windows runs; debug it with F9 in Asmonite
  examples\arm64\   a64asm_hello.asm: the same for ARM64 (.arch arm64), for a
                    Windows on ARM64 computer (set up the debug target)
  qemu\run_buster.bat  Raspberry Pi OS (ARM) in QEMU, for debugging ARM
                    programs with Dismonite (see below)
  qemu\run_freedos.bat FreeDOS in QEMU; loads the FreeDOS floppy that
                    Asmonite and Dismonite need for DOS programs
  debugserver\asmodbg.exe  debug server for the Windows on ARM computer (see below)
  debugserver\asmodbg64.exe  the same for ARM64 programs (runs on Windows on ARM64)
  debugserver\asmodbgx64.exe  debug server for x64 programs on this computer
  LICENSE.txt       the license
  CHANGELOG.md      what has changed

First steps
  1. Unpack the folder anywhere, there is no installation.
  2. Start Asmonite.exe and open examples\windows_intel\demo.asm.
  3. Ctrl+F9 assembles, F9 runs the program in the debugger,
     F5 sets a breakpoint, F8/F7 step through it.

Note: the programs are not signed. Windows may therefore ask on the first
start ("Windows protected your PC" -> "More info" -> "Run anyway").

For debugging DOS programs Asmonite and Dismonite need QEMU
(https://www.qemu.org) and a FreeDOS floppy (https://www.freedos.org). Start
qemu\run_freedos.bat once: it loads the floppy (720 KB, after asking) to
qemu\freedos\freedos.img and offers to install QEMU if it is missing
(winget; on Windows on ARM the native ARM64 build of qemu.weilnetz.de).
Asmonite and Dismonite find the floppy there. To try it: open
examples\dos\HELLO.EXE in Dismonite, F7 starts QEMU and stops at the entry
point.

Dismonite debugs ARM programs (Linux, ELF) in Raspberry Pi OS under QEMU:
start qemu\run_buster.bat. On its first start it loads the missing files
(about 440 MB, after asking) and sets up the system (a few minutes, needs
internet); if QEMU is missing, it offers to install it (as above).
"run_buster -h" shows the options. Login: pi / raspberry.

Dismonite debugs ARM programs for Windows on ARM (PE, machine 0x1C4) on a real
Windows on ARM computer. First-time setup (two computers):
 1. On the ARM computer, in a normal (not administrator) command prompt:
      powershell -NoProfile -Command "irm https://asmonite.com/downloads/install-asmodbg.ps1 | iex"
    The line downloads asmodbg.exe to C:\Users\<name>\asmodbg, checks its checksum
    and starts the server (an older version is replaced). Dismonite shows the line
    to copy in the dialog "Debug target Windows on ARM". Without internet: copy
    debugserver\asmodbg.exe into a folder of its own by hand and start it with a double
    click, NOT as administrator. Windows may warn (not signed, "More info" ->
    "Run anyway"). A small window opens (in compatibility mode, the text may look blurred):
    "... OK", the IP addresses, the port (23457), the code (XXXX-XXXX-XXXX) and
    the status. Keep the window open while you debug. The computer must not go
    to sleep meanwhile (Dismonite then only reports "no connection"): run it on
    its power supply and enter once in a command prompt
      powercfg /change standby-timeout-ac 0
      powercfg /change monitor-timeout-ac 0
    (on ARM laptops turning off the display alone can start the sleep).
 2. Firewall: on its first start Windows asks on the screen of the ARM computer
    whether asmodbg may use the network. Confirm "Allow" there (also for the
    kind of network the computer is in; Wi-Fi often counts as "public"). If that
    was missed, once in a command prompt as administrator (adjust the path):
      netsh advfirewall firewall add rule name=asmodbg dir=in action=allow
        program="C:\Users\<name>\asmodbg\asmodbg.exe" protocol=TCP
        localport=23457 remoteip=localsubnet profile=any
    and the same line once more with protocol=UDP (for "Search LAN" in Dismonite).
    The rules only let computers of the same local network in.
 3. On the development computer: open an ARM PE program in Dismonite (to try it:
    examples\winarm\pe_arm32_hello_world.exe) and press
    F9 (or F7/F8). As no target is set up yet, "Debug target Windows on ARM"
    opens (also any time under Debug). Choose "Direct", press "Search LAN" (it
    finds the running asmodbg in the network and fills in address and port; else
    type both from the window), enter the code and press "Test connection". When it
    says "OK", save with OK: Dismonite uploads the program, starts it there and
    stops at the entry point. The program's output appears in the output view.
 Notes: the code protects the server (login and a checksum on every packet, no
 encryption); it is stored protected with DPAPI next to asmodbg.exe, "asmodbg
 --new-code" makes a new one. asmodbg.exe and Dismonite must have the same
 version (the test says so); then copy the server again by hand. Use it only in
 a network you trust: the program really runs there. Alternative without the
 asmodbg window: the "ssh" target (key login to the computer needed; Dismonite
 copies the server itself).

ARM64 programs (PE, machine 0xAA64) work the same way, but with the server
debugserver\asmodbg64.exe on the Windows on ARM64 computer: copy and start it like
asmodbg.exe (double click, not as administrator; the dialog "Debug target Windows
on ARM" is the same, the "ssh" target also copies it itself). In direct mode both
servers take port 23457: only one runs at a time; to have both, give one of them
another port with "--port" and enter the same number in Dismonite. In the Windows
firewall asmodbg64.exe needs a rule of its own (as above, with the path of
asmodbg64.exe).

x64 programs (PE, machine 0x8664) Dismonite debugs on its own computer: a 32-bit
program cannot debug a 64-bit process, so Dismonite starts
debugserver\asmodbgx64.exe itself as a child process (no login code, no firewall
rule, only the loopback address). F9/F8/F7 as usual.
