Tekst źródłowy strony EM400 - tekstowy interfejs użytkownika

EM400 poza interfejsem graficznym Qt6 udostępnia prosty interfejs tekstowy, przeznaczony przede wszystkim do sterowania emulatorem przez inny program. Używają go na przykład testy emulatora. Jego konstrukcja umożliwia również sterowanie emulatorem przez użytkowników potrzebujących instalacji "headless".

= Uruchomienie =

 em400 -u cmd

Interfejs działa wówczas na standardowym wejściu/wyjściu procesu.

 em400 -u cmd:<port>

Interfejs nasłuchuje na wskazanym porcie TCP na interfejsie loopback (127.0.0.1).

= Protokół =

Komunikacja odbywa się tekstowo. Każda komenda to linia zakończona znakiem nowej linii. Każda odpowiedź to równiż jedna linia, zaczynająca się od statusu:

 OK: <wynik>
 ERR: <opis błędu>

Uwagi:

* Nazwy komend nie rozróżniają wielkości liter.
* Argumenty rozdziela dowolny biały znak.
* Maksymalna długość linii wejściowej to 65536 bajtów. Dłuższa linia jest odrzucana w całości z błędem.

== Format liczb ==

Argumenty liczbowe są interpretowane według prefiksu:

{| class="wikitable"
! Zapis !! Podstawa !! Przykład
|-
| <code>0x...</code> || szesnastkowo || <code>0x40</code>
|-
| <code>0...</code> || ósemkowo || <code>0100</code>
|-
| pozostałe || dziesiętnie || <code>64</code>
|}

Dopuszczalny zakres to -32768..65535. Wartość jest obcinana do 16 bitów.

Argumenty typu włącz/wyłącz przyjmują wyłącznie <code>on</code> i <code>off</code>.

= Lista komend =

{| class="wikitable"
! Komenda !! Argumenty !! Opis
|-
| <code>help</code> || <code>[komenda]</code> || Lista komend lub opis wskazanej komendy
|-
| <code>info</code> || || Wersja emulatora
|-
| <code>state</code> || || Stan procesora
|-
| <code>reg</code> || <code>[nazwa [wartość]]</code> || Odczyt/zapis rejestrów
|-
| <code>int</code> || <code>[numer]</code> || Odczyt rejestru RZ lub zgłoszenie przerwania
|-
| <code>mem</code> || <code>seg adres liczba_komórek</code> || Odczyt pamięci
|-
| <code>memw</code> || <code><seg> <adres> <wartość> ...</code> || Zapis pamięci
|-
| <code>memmap</code> || <code>seg</code> || Mapa alokacji dla segmentu
|-
| <code>load</code> || <code>seg adres plik</code> || Załadowanie pliku do pamięci
|-
| <code>eval</code> || <code>wyrażenie</code> || Obliczenie wyrażenia
|-
| <code>brk</code> || <code>wyrażenie</code> || Dodanie pułapki
|-
| <code>brkdel</code> || <code>id</code> || Usunięcie pułapki
|-
| <code>start</code> || || uruchomienie procesora (podniesienie klucza START)
|-
| <code>stop</code> || || zatrzymanie procesora (opuszczenie klucza START)
|-
| <code>cycle</code> || || Wykonanie jednego cyklu (klucz CYCLE)
|-
| <code>clear</code> || || zerowanie, reset (klucz CLEAR)
|-
| <code>bin</code> || || start ładowania binarnego (klucz BIN)
|-
| <code>oprq</code> || || zgłoszenie operatora (klucz OPRQ)
|-
| <code>clock</code> || <code>[on|off]</code> || Stan zegara lub jego włączenie/wyączenie (klucz CLOCK)
|-
| <code>ips</code> || || Średnia liczba instrukcji na sekundę
|-
| <code>log</code> || <code>[on|off]</code> || Stan logowania lub jego włączenie/wyłączenie
|-
| <code>logc</code> || <code>[komponent [stan]]</code> || Stan komponentów logowania lub ich włączenie/wyłączenie
|-
| <code>quit</code> || || Zakończenie pracy emulatora
|}

= Opis komend =

== state ==

Zwraca bieżący stan procesora.

 > state
 OK: STOP

== reg ==

Bez argumentów wypisuje wszystkie rejestry:

 > reg
 OK: R0=0x0000 R1=0x0000 R2=0x0000 R3=0x0000 R4=0x0000 R5=0x0000 R6=0x0000 R7=0x0000 IC=0x0040 AC=0x0000 AR=0x0000 IR=0x0000 SR=0x0000 RZ=0x0000 KB=0x0000

Podanie nazwy rejestru pokazuje zawartość wybranego rejestru, a nazwy i wartości powoduje jej zapis do rejestru:

 > reg ic
 OK: 0x0040
 > reg ic 0x70
 OK: 0x0070

Dostępne rejestry: R0-R7, IC, AC, AR, IR, SR, RZ, KB (klucze binarne pulpitu)

== int ==

Bez argumentu zwraca 32-bitowy rejestr zgłoszeń RZ. Z argumentem (0..31) zgłasza przerwanie o podanym numerze i zwraca RZ po zgłoszeniu.

 > int
 OK: 0x00000000
 > int 5
 OK: 0x04000000

== mem ==

Odczytuje wymaganą liczbę słów z danego segmentu począwszy od podanego adresu. 

 > mem 0 0x40 4
 OK: 0x0000 0x0000 0x0000 0x0000

== memw ==

Zapisuje kolejne słowa począwszy od podanego adresu. Liczba wartości jest
dowolna (do rozmiaru segmentu).

 > memw 0 0x40 0x1234 0x5678
 OK: 2 words written

== memmap ==

Zwraca mapę zajętości segmentu jako 16-bitową maskę stron.

 > memmap 0
 OK: 0x000f

== load ==

Ładuje plik do pamięci.

 > load 0 0 test.bin
 OK: 1024 words loaded from file test.bin

== eval ==

Oblicza wyrażenie w kontekście bieżącego stanu maszyny i zwraca wynik dziesiętnie.

 > eval r0 + 1
 OK: 5
 > eval [0:0x40]
 OK: 4660

W przypadku błędu składni zwracany jest komunikat wraz z pozycją w tekście:

 > eval r0 +
 ERR: syntax error, unexpected end of file (at 6-6)

== brk / brkdel ==

Pozwala dodać pułapkę. Pułapka jest wyrażeniem obliczanym przed każdą instrukcją. Gdy wynik jest niezerowy, procesor jest zatrzymywany. Zwracany jest numer
pułapki, służący później do jej usunięcia.

 > brk ic == 0x100 && r1 > 0
 OK: Added breakpoint: 0
 > brkdel 0
 OK: Removed breakpoint: 0

== clock ==

Zwraca stan lub włącza/wyłącza zegar (timer zgłaszający przerwanie zegarowe).

 > clock
 OK: 1
 > clock off
 OK: 0

== ips ==

Średnia liczba wykonanych instrukcji na sekundę od poprzedniego wywołania.

 > ips
 OK: 1934281

== log / logc ==

<code>log</code> włącza i wyłącza logowanie jako całość, <code>logc</code> zarządza poszczególnymi komponentami logowania.

 > log on
 OK: 1
 > logc
 OK: LIB APP CPU
 > logc mx 1
 OK: 1
 > logc mx
 OK: 1

Opis komponentów można znaleźć [https://mera400.pl/EM400_-_konfiguracja#Logowanie tutaj]

== quit ==

Kończy pracę emulatora.

= Składnia wyrażeń dla brk i eval =

Ta sama składnia obowiązuje w komendach <code>eval</code> i <code>brk</code>. Wielkość liter nie ma znaczenia.

= Literały =

{| class="wikitable"
! Zapis !! Znaczenie
|-
| <code>123</code> || dziesiętnie
|-
| <code>0x1f</code> || szesnastkowo
|-
| <code>017</code> || ósemkowo
|-
| <code>0b1010</code> || dwójkowo
|}

= Elementy stanu maszyny =

{| class="wikitable"
! Zapis !! Znaczenie
|-
| <code>r0..r7</code> || rejestry ogólnego przeznaczenia
|-
| <code>ic, ac, ar, ir, sr, kb</code> || rejestry systemowe
|-
| <code>z m v c l e g y x</code> || flagi (bity rejestru R0)
|-
| <code>rz</code> || rejestr zgłoszeń przerwań
|-
| <code>rz[n]</code> || pojedynczy bit rejestru zgłoszeń
|-
| <code>alarm</code> || stan ALARM
|-
| <code>mc</code> || licznik pre-modyfikacji
|-
| <code>rm, q, bs, nb</code> || pola rejestru SR
|-
| <code>[adres]</code> || słowo pamięci w bieżącym bloku
|-
| <code>[blok:adres]</code> || słowo pamięci w podanym bloku
|-
| <code>@ramka:segment</code> || fizyczne położenie segmentu
|}

= Operatory =

Od najwyższego priorytetu:

 [ ]
 ~ !
 * /
 + -
 <<
 >>
 <  >  <=  >=
 !=  <>
 ==
 &
 ^
 |
 &&
 ||

Dostępny jest także jednoargumentowy minus oraz nawiasy okrągłe.