﻿
                          P I K A S M
                          -----------

Pikasm  je  assembler-editor  od T.R.C. vybavený  kompresí  dat,
64znakovým editorem,  podmíněným  překladem, blokovými operacemi
a  dalšími  vymoženostmi.  Řada funkcí Pikasmu je  však  neznámá
a k jejich objasnění má posloužit tento manuál. Manuál je členěn
takto: editor, hlavní menu, překladač, konfigurace.

Pikasm 1.5 je první verzí pro esxDOS,  umožňující  přímé čtení a
zápis zdrojových souborů na SD/CF kartu. Navazuje na Pikasm 1.1+
tj. verzi vylepšenou Pevosoftem  o práci  s bloky a vyhledávání.
Verze 1.5 je optimalizována  v  některých  funkcích  i rychlosti
tisku znaků, obsahuje init (konfigurátor) a je zbavena rutin pro
práci  s mgf. páskou,  které jsou  nahrazeny  voláními  esxDOSu.
Import  a export souborů  s emulací pásky jsou  v esxDOSu snadno
dostupné jinak, pomocí řady příkazů  a systémových utilit, např.
přímo v NMI/LFN Browseru nebo v LnxCopy pro eZX/MB.

Z  verze  Pikasm+Mon  byla vyčleněna samostatná utilita, tečkový
příkaz pro esxDOS: .PIK2GENS,  který  převede  zdrojáky staršího
assembleru GENS do formátu Pikasmu.


                           1. EDITOR
                           ---------

Editor má 64 znaků  na 22 řádcích. Předposlední řádek zobrazuje
tabulátory, poslední řádek pak ukazuje:
 - zapnutí CAPS LOCKu
 - délku souboru,
 - volné místo k pracovnímu RAMTOPU (ve Workspace)
 - počátek zdroj. kódu (hranici Workspace)
 - hodnotu 16bitové systémové proměnné OPT.

1.1 Instrukce

Instrukce  zapisujeme  na  řádce  s  kurzorem,  přičemž nemusíme
dodržovat tabulátory - program si totiž vždy řádku sám srovná.

Každá  řádka  může  začínat návěstím (max 8 znaků dlouhé). Pokud
návěstí  vynecháme,  je nutné vložit nejméně jednu mezeru (jinak
by se totiž instrukce brala jako návěstí). Výjimkou jsou prázdná
a poznámková řádka (prefix ;).

Dále  následuje  samotná  instrukce  (např.  LD,  NOP, ADD) nebo
pseudoinstrukce assembleru.

Pikasm ovládá všechny instrukce Z80, včetně všech ~tajných~. To
jsou:
      1) Instrukce pracující s  polovinami  registrů  IX  a  IY,
         které v zápisu  označujeme  LX,HX,LY  a  HY
         (např.  LD  A,LX). Program ošetřuje prefixové chyby
         (např. LD LX,LY).
      2) Shiftový posun vlevo, který dává  do  nultého  bitu  1.
         Program akceptuje zápis SLL i SLIA.
      3) Bitové  instrukce  a  instrukce  posunu  s   přesunem.
         Jsou   to   RL,RR,RLC,RRC,SLA,SRA,SRL,SLL,SLIA,RES,SET.
         Je zajímavé, že program  překládá  i  BIT,  který  však
         přesun neprovádí. V zápisu např. RES 6,C,(IX+10).

Pseudoinstrukce nejsou instrukcemi procesoru, slouží  především
k řízení překladu. Jsou to:
      DB       definované bajty.  Za  tímto  příkazem  musí  být
               nejméně  jeden  výraz  <-255,255>.  (Pozn.   více
               příkazů oddělujeme čárkami (,)).
      DW       definovaná slova.  Za  tímto  příkazem  musí  být
               nejméně jeden výraz <-65535,65535>.
      Speciálními typy výrazů jsou:
          Znak:  Zapisujeme mezi dva apostrofy. Možnost  prefixů
                 / (lomítko) a ^ (šipka, mocnina)-viz text.
          Text:  Zapisujeme mezi dvoje uvozovky, může mít  délku
                 max 47 znaků. Lze zapsat malá, velká  písmena a
                 znaky  extend   modu.   Pokud   chceme   vložit
                 znak+128 (např. zarážka),  napíšeme  před  znak
                 prefix ^ (např. ^a). Pokud chceme  zapsat  znak
                 ^, musíme  použít  prefixu  /  (/^).  Prefix  /
                 umožňuje i vložení dalších kódů:
                    //  = lomítko
                    /"  = uvozovky
                    /n  = chr 13, enter
                    /l  = chr 6, left
                    /0  = chr 0
          Sequence: Jedná se o posloupnost hexa čísel  uvedených
                 dvojtečkou  (např  :AB0F).  Pokud   chceme   do
                 sequence  zařadit  znak,  použijeme  prefix  ".
                 Pro znak+128 použijeme prefix ^.
          Slovo: Chceme-li  mezi  řadu  bajtů   vložit   slovo,
                 použijeme prefix >.
          Byte:  Pro vložení bajtu do řady slov použijeme prefix
                 <.
      DS      definované místo. Určuje počet rezervovaných  bytů
              v paměti. Druhý výraz pak určuje čím se  má  místo
              vyplnit (Např.  DS   230    =  230  volných  bytů,
              DS 15,#ff =  patnáct  dvěstěpadesátpětek).   Pokud
              neuvedete  plnící  znak,   rezervované   byty   se
              přeskočí a nezmění.
      ORG     Začátek překladu. Tato  instrukce  určuje  kam  se
              bude kód překládat. Případný druhý parametr  udává
              adresu skutečného překladu (např  ORG  16384,50000
              zajistí uložení kódu fungujícího  v  obrazovce  od
              adresy 50000).
      EQU     přiřazení.  Tato  instrukce   přiřazuje   návěstí
              hodnotu určenou výrazem vpravo (např DESET EQU 10)
      OPT     Nastavení lokálních Options. Viz Options.
      OPSET   Nastavení jistých lokálních Options. Provede se OR
              parametru s lokálními Options.
      OPRES   Vypnutí jistých lokálních Options. Provede se  CPL
              a AND parametru s lokálními Options.
      OPXHG   Přepnutí jistých lokálních Options. Provede se XOR
              parametru s lokálními Options.
      ENTER   Vstupní bod. Tento příkaz určuje vstupní  bod  pro
              příkaz  RUN  (viz  dále).  Parametr  určuje  přímo
              adresu, bez parametru  se  bere  aktuální  hodnota
              čítače (= ENTER $).
      IF      Podmínka.  Určuje  začátek  podmíněného  překladu.
              Pokud je výraz vyhodnocen jako pravdivý,  překládá
              se část programu až do ENDIF (resp.  ELSE).  Pokud
              je výraz nepravdivý,  část  k  ENDIF  se  ignoruje
              (resp. přeloží se část po ELSE).
      ELSE    Pokud byl výraz po IF pravdivý, přeloží se  část
              programu až k tomuto příkazu a následující část se
              bude ignorovat  až  k  příkazu  ENDIF.  V  opačném
              případě se první část ignoruje a druhá přeloží.
      ENDIF   Konec podmínky.
      BRON    Break on. Parametr jako u ENTER. Od tohoto příkazu
              se až k příkazu BROFF (resp.  do  konce  programu)
              budou  do  výsledného  kódu  ukládat  odskoky   do
              Pikasmu umožňující přerušení programu. Ten je však
              nutno volat z Pikasmu  (Run).  Vhodné  pro  ladění
              programů (možnost  přerušení  nekonečných  cyklů).
              Při  finálním  překladu  však  nezapomeňte   tento
              příkaz vypnout. Také pozor na problémy s např.  JR
              NZ,$+3 a podobnými "absolutními" konstrukcemi.
      BROFF   Break off. Vypíná vkládání kontrolních odskoků  do
              kódu. Implicitně je na konci programu.

1.2 Operátory a zápis hodnot

Pokud  to instrukce vyžaduje, následují na řádce operandy, příp.
parametry. Podstatnou součástí operandů a parametrů jsou výrazy.
Výraz  je  v  podstatě  posloupností  návěstí  (příp.  hodnot) a
operátorů.

Operátory jsou:
      1) unární. Pracují pouze s jedním parametrem.
          . (tečka)       Logická negace                (CPL)
          - (mínus)       Opačná hodnota                (NEG)
          + (plus)        lze vynechat
          \ (obr.lomítko) Vyšší byte
          / (lomítko)     Nižší byte
      2) binární. Stojí mezi dvěma výrazy.
          + (plus)        Součet
          - (mínus)       Rozdíl
          * (hvězdička)   Násobení
          / (lomítko)     Dělení                        (DIV)
          \ (obr.lomítko) Zbytek po dělení              (MOD)
          & (and)         Bitový AND
          | (čárka)       Bitový OR
          ~ (vlnovka)     Bitový XOR
          && (2x and)     A zároveň, logický AND
          || (2x čárka)   Nebo, logický OR
          ~~ (2x vlnovka) Výlučné nebo, logický XOR
          >               Větší než
          <               Menší než
          >=              Větší nebo rovno
          <=              Menší nebo rovno
          =               Rovnost
          <>              Nerovnost
          <<              Rotace vlevo (např 10<<2)     (SLA)
          >>              Rotace vpravo o N bitů        (SRL)

     Pozn. pozor na vyhodnocování zleva doprava (2+3*4 =20)

Kromě  návěstí  se  ve  výrazech  vyskytují i konkrétní hodnoty.
Existuje několik způsobů jejich zápisu.

     Prefix    Hodnota
     Žádný     Normální decimální zápis
       #       Hexadecimální zápis (např. #28FF)
       %       Binární zápis (např. %01011000)

Speciálním  případem  je  zápis jednobytové hodnoty formou znaku
(viz též DB,DW). Požadovaný znak vložíme mezi apostrofy (').

Nezaměňovat  s  textem, který je vložen mezi uvozovky (") a může
obsahovat i více znaků. Např. 'a' je normální hodnota rovná 97 a
lze  použít ve všech výrazech. Oproti tomu "a" je text, a lze ho
použít pouze v pseudo instrukcích DB a DW.

Specialitkou  je  též  čítač  adres  $  (string).  Je vždy roven
aktuální adrese.

1.3 Řídící klávesy

Editor sám o sobě má vestavěn řadu užitečných funkcí, které  se
ovládají řídícími klávesami:
 CS+1 ......   Posun kurzoru po tabulátorech vlevo.
 CS+SPACE      Posun kurzoru po tabulátorech vpravo.
 CS+8          Posun kurzoru vpravo.
 CS+5          Posun kurzoru vlevo.
 CS+7          Posun kurzoru nahoru.
 CS+6          Posun kurzoru dolu.
 CS+2 (CAPS)   Přepínání malá/velká písmena.
 CS+3          Vlož mezeru. Zbytek řádky se posune doprava.
 CS+4          Vymaž znak na pozici  kurzoru.  Řádka  se  posune
               doleva.
 CS+0          Vymaž znak vlevo a posun kurzoru doleva.
 CS+9          Vlož jednu řádku před aktuální řádku.
 ENTER         Vlož  jednu  řádku  za  aktuální  řádku + přechod
               kurzoru na novou řádku.
 CS+SS (EXT.)  Přechod do menu.
 SS+W          Vymaž aktuální řádku.
 SS+Q          Zapamatuj si aktuální řádku.
 SS+E          Vlož poslední zapamatovanou řádku.

Pozn. Pokud dojde po odeslání řádku ke ztrátě dat na jeho konci,
Pikasm na to upozorní barevným atributem.

1.4 Chybová hlášení editoru

Při  použití  ENTER,  CS+7, CS+6, CS+9 a CS+SS kontroluje Pikasm
syntax  dopsané řádky. Pokud není něco v pořádku, napíše některé
z chybových hlášení:

Illegal character   V  návěstí  příkazu   nebo   operandech   se
                    vyskytuje  nesprávný  znak.
Bad operands        Instrukce  obsahuje  operand(y),   jenž   jí
                    nepřísluší.
Label too long      bylo použito nebo deklarováno návěstí  delší
                    než 8 znaků.
Is a reserved word  Bylo  použito  nebo  deklarováno  návěstí  s
                    názvem stejným jako označení registrů.
Bad mnemonics       Nesmyslná instrukce. Např. "spojeně" zapsáno
                    LDA,1 apod.
Not closed          Chybí uvozovky ukončující text.
Character error     Použití  prefixu  /  v  textu   se   špatným
                    parametrem.
Prefix error        Instrukce operující s registry IX či  IY  je
                    nepřeložitelná, např. ADD IX,IY.
Out of memory       Není dostatek  volné  paměti,  nutno  zvýšit
                    Workspace.

Během  provádění  některých příkazů editoru mohou dále vzniknout
tyto chyby:

Interrupted                Break při I/O operacích nebo
                           přerušení programu s povoleným BRON.
Printer sequence invalid   Zadávaná sekvence znaků nemá správnou
                           syntax.
Ramtop too low             Špatně nastavený Workspace.
Invalid request            Pokus o RUN  při  neznámém  ENTER  či
                           chyba při operacích s bloky.

Při  esxDOSových  operacích  LOAD  a SAVE  se  mohou  vyskytnout
následující hlášení:

File not found             Load: soubor neexistuje.
                           Save: cílový adresář/cesta
                                 neexistuje
Disk full                  Nedostatek místa na kartě
Out of memory              jen Load: soubor se nevejde do RAM
                           (za zdroj + symboly, pod Workspace)
File exists, overwrite?    jen Save: dotaz na přepis souboru
Disk error                 jiná chyba


                         2. HLAVNÍ MENU
                         --------------

Stisknutí  CS+SS  nás přepíná mezi editorem a hlavním menu. Menu
nabízí funkce, které se vyvolají stisknutím prvního písmena.

 2.1 Příkazy menu

 Asm           Spuštění překladu. Viz Překladač.
 Run           Spustit program od adresy udané  v direktivě
               ENTER. (Nelze pokud byly chyby při překladu nebo
               nebyl vložen žádný vstupní bod).
 Bas           Návrat do BASICU.
 Cpy           Zkopírování bloku.
 Del           Vymazání bloku.
 Fnd           Vyhledání (především návěstí).
 Nxt           Vyhledání dalšího výskytu.
 Loa           Načtení (přihrání) souboru podle zadaného jména.
               Před souborem lze uvést relativní nebo absolutní
               cestu s adresáři, např.: SRC/SIPKA.SRC
 Sav           Uložení souboru se zadaným jménem.
 Qpt           Sequence znaků posílané na tiskárnu na  začátcích
               a koncích stránek a řádek. Výstup na tiskárnu  je
               přes kanál #3.
 Opt           Options pro překladač. Jedná se  o  16-ti  bitové
               číslo, jehož jedničkové bity mají tyto významy:
               Hodnota   Bit       Význam
               1         0         Na konci  výpisu  se  provede
                                   abecedně řazený  výpis  všech
                                   návěstí
               2         1         Výsledný  kód  se   fyzicky
                                   neukládá
               4         2         Neprovádí se listing
               8         3         Výstup na tiskárnu
               16        4         Překlad   se   provádí   za
                                   Workspace
               32        5         Nekontroluje  se   umístění
                                   výsledného kódu
               64        6         Výstup na tiskárnu (jako 3)
               128       7         Nevypisují se čísla řádek
               256       8         Při chybě skok do editoru
               512       9         Následující text ignoruj
               1024      10        Nevyužito
               2048      11        Výpis adres v hexa
               4096      12        Zobrazení  skutečné  adresy
                                   uložení
               8192      13        Výpis vytvářeného kódu
               16384     14        Při chybě a 8 bitu se nečeká
                                   na stisk klávesy
               32768     15        Pro vnitřní  potřebu  Pikasmu
                                   (Bron/Broff)
 Tab           Změna tabulátorů. Pozn. program  ignoruje   změnu
               tabulátorů  pokud   jde   o   umístění   návěstí,
               instrukce a operandů v řádku.
 Wrk           Nastavení vrcholu zdrojového prostoru (konec
               Workspace, hranice textu+návěstí/ začátek volného
               prostoru)
 Min           Nejnižší možné nastavení hranice Workspace
               (snížení dle zaplněného text + návěstí).
               Min nelze aktivovat do platného překladu, až
               bude jasná tabulka návěští.
 Xlr           Vymazat všechen zdrojový text.

 V režimu CS+SS dále fungují tyto stránkovací klávesy:
  5, vlevo     začátek textu
  6, dolů      o stránku vpřed
  7, nahoru    o stránku vzad
  8, vpravo    konec textu

2.2 Kopírování bloku řádek

Funkce pracuje s řádkovým blokem  - při označování rozhoduje jen
řádek, na  kterém  stojí  kurzor, ne jeho pozice ve sloupci.  Ve
spodním řádku se objeví nabídka:
   COPY > Frst Last Dest Quit 5B 8E 6+ 7- curs

Po textu se lze pohybovat stránkovacími klávesami 5/6/7/8 nebo
kurzory. Blok  se  označuje  ve  třech  krocích,  které je nutné
provést v následujícím pořadí:
      F (Frst)   Označí první řádek bloku.
      L (Last)   Označí poslední řádek bloku.
      D (Dest)   Označí cílový řádek
                 Po stisku D se blok zkopíruje.

Cíl nesmí ležet uvnitř vybraného  bloku; Klávesou  Q  (Quit) lze
operaci kdykoli zrušit beze změny.

2.3 Delete block

Příkaz  Del  zapne  režim mazání bloku řádek. Stejně jako u Copy
jde o celé řádky. Ve spodním řádku se objeví nabídka:
   DELETE > Frst Last Quit 5B 8E 6+ 7- curs

      F (Frst)   Označí první řádek bloku.
      L (Last)   Označí poslední řádek bloku.
                 Po stisku L se blok okamžitě smaže.
      Q (Quit)   Zruší operaci beze změny.


                          3. PŘEKLADAČ
                          ------------

Překladač  Pikasmu  má  dva  průběhy.  Během  prvního  assembler
vytváří  tabulku návěstí a jejich hodnot. Při tomto průběhu může
dojít k těmto chybovým hlášením:

  Duplicate declaration:XXXXXXXX
         V programu se vyskytuje návěstí XXXXXXXX, které bylo
         definováno vícekrát.
  Expression not defined
         V pseudoinstrukci byl použit nedefinovaný výraz.
  No table space
         Není dost volné paměti pro vytvoření tabulky návěstí.
         (je nutno zvýšit hodnotu Workspace)
  IF overflow
         V programu se vyskytuje více než 15 příkazů IF, které
         jsou do sebe vnořeny.
  IF underflow
         Více příkazů ENDIF než If.
  More IFs than ENDIFs
         Ne všechny bloky IF jsou zakončeny ENDIF.

Po ukončení běhu prvního průběhu Pikasm oznámí:
      -1st pass finished..

a  začíná  průběh  druhý. V druhém průběhu překladače se vytváří
vlastní program. Při tomto průběhu se může vyskytnout hlášení:

  Bad ORG
         Pokus  o  fyzické  zapsání  bytu  do  oblasti   začátek
         Pikasmu až Workspace.  Kontrolu  i  fyzický  zápis  lze
         vypnout bity 1 a 5 (viz Options).
  Out of range
         Výraz nabývá hodnoty mimo povolený interval: <-255,255>
         byte,  <-65535,65535>  slovo  a  <-128,127>   relativní
         adresace skoků a indexregistrů.

Po ukončení druhého průběhu Pikasm vypíše:
  Non defined symbols:

a následuje výpis všech návěstí, která nebyla definována.
Všechny operace s těmito návěstími se přeloží jako kdyby návěstí
mělo hodnotu 0.

Pokud jste nastavili bit 0 v Options, překladač ještě vytiskne:
  Defined symbols:

a  abecední  seznam všech definovaných návěstí. Nakonec se ještě
dozvíme, že
  2nd pass finished.
  Workspace used: x/y

kde x je počet bytů použitých pro pracovní tabulku návěstí a
    y je počet volných bytů od konce zdrojového textu až po
hranici Workspace.

Odtržení na konci překladu ocení majitelé tiskáren.

Překlad  je  možno  kdykoliv  pozastavit  stiskem  SPACE  a poté
ukončit  klávesou Q  (hlášení  'Interrupted' a skok do editoru).
Cokoliv jiného pokračuje v překladu.


                          4. KONFIGURACE
                          --------------

Zavaděcí soubor  PIKASM15.COD je spuštěn  v prostoru  obrazovky.
Instaluje  vlastní exec Pikasmu,  soubor PIKASM15.BIN,  do něhož
aplikuje hodnoty proměnných ze souboru PIKASM15.CFG. Jedná se o:

barvy
   PAPER=0
   INK=6
   BRIGHT=1

hranici pracovního prostředí (také nastavitelné z menu, Wrk)
   WORKSPACE=54000

některé bity z proměnné OPT (také nastavitelné z menu, Opt)
   LIST_SYMBOLS=1
   SUPPR_STORE=0
   SUPPR_LIST=1
   PRINTER=0
   BEHIND_WS=0
   NOADDRCHECK=0
   PRINT_FLUSH=0
   NOLINENUMS=0
   SHOWERRORS=1
   LIST_HEX=0
   NOLISTPAUSE=1

V přípravě je možnost změny fontu, znakové rutiny a velmi
pravděpodobně i grafického módu (hires).

PIKASM15.CFG může být také uložen v adresáři /SYS/CONFIG.


                          (C) RAXOFT Praha 02.32 ráno 15.10.1990
                     taky SOFTWARE 2000 OF CERES-SOFT 03.02.1991
                                   doplnil SCjoe v červenci 2026
