***************************
* Asm Flash Documentation     *
*    1/10/91 By HPNinja           *
***************************


Le Contenu
----------
C'est la librairie 864 Asm Flash. Elle est compose de 4 fonctions:
    * ->ASM   l'assembleur lui-mme
    * ASM->   le dsassembleur
    * ED      l'diteur d'erreurs
    * OPT     le menu d'options
    * INFO864 un petit memo et un petit info

 1. La Syntaxe
-------------
    Elle utilise le format des instructions de Voyage Au Centre de la 48SX,
        quelques exceptions prs. En effet, pour simplifier on utilise
          pour les instructions D0= D1= LCHEX LAHEX la syntaxe suivante:
          D0= 12345   au lieu de D0=(5) 12345
          D0= 12      au lieu de D0=(2) 12
          LCHEX 12345 au lieu de LCHEX(5) 12345
          ou encore plus court, LC 12345, tout simplement

    Exemple: *LABEL (sans espace aprs l'astrisque)
    L'assembleur ne tient pas compte des espaces avant ou aprs les labels.
    On peut mettre autant de marge que l'on veut.
    On peut aussi inclure des commentaires, dclars par un %.
       ex:   A=DAT0    A    % l'Asm Flash, c'est super!
    ou sans instruction: % J'ai pt une Casio aujourd'hui.
    Attention: Tout source doit finir par un Carriage Return et un Arobas!
       (en clair: un saut de Newline et un @), pas de caractres aprs.

2.La Compilation
---------------------
     Vous entrez une chaine de caractres qui reprsente votre source, chaque
     instruction tant spare par un espace, et vous lancez ->ASM.
    Exemple:
    Mon source est A=DAT0 A
                   D0=D0+ 5
                   PC=(A)
                   @
    Utilisons  prsent le menu d'options...
    Quand vous le lancez, apparait une barre de menu:

    - Code ou Hexa
        L'assembleur retournera au choix un opbjet Code, executable ou
        une chaine de caractres ou le code est en Hexa

    - 0-15 ou 1-16
      Si c'est 0-15, la numrotation de quartets se fera de 0  15, comme
        dans Voyage. Cela concerne les instructions P=, CPEX, C=P, P=C,
        ABIT=0, ABIT=1, CBIT=0, CBIT=1, ?ABIT=0, ?ABIT=1, ?CBIT=0, ?CBIT=1,
        ?P=, ?P<>, HS=0, ?HS=0
      Si c'est 1-16, la numrotation se fera de 1  16, comme le veut la
        syntaxe HP Normalise. Ce n'est pas trs logique, car le champ P
        par ex tient sur 1 quartet, donc vaut de 0  15.
      Comme pour les instructions A=R0 A ou elle prfre crire A=R0.F A
    
- HP ou PC
      Si c'est HP, les caractres de comparaison seront ceux de la HP48SX,
         ou >= et <= tiennent sur 1 caractre.
      Si c'est PC, ce seront cette fois ceux de l'ordinateur:
         * >= pour suprieur ou gal   * <= pour infrieur ou gal
         * #  pour diffrent, et non pas <>, c'est la syntaxe HP normalise.
    - JMP ou UNJ
      Si c'est JMP, tous les sauts seront compils, c'est pour la compilation
         normale. Si c'est UNJ, les sauts sur les labels ne seront pas vrifis
         ni calculs, et l'assembleur retournera un System Binary indiquant la
         taille du programme en quartets, cela sert si vous voulez connaitre
         la taille d'une partie de programme  l'avance.

    Exemple: j'ai un gros programme dont une partie est
             SHUTDN
             GOTO SmallLabel
          A=DAT0 A
          GOTO BigLabel
    Comme on le voit, dans cette partie, les labels SmallLabel et BigLabel
    n'ont pas t dclar, donc si je mets JMP, il y aura une erreur, alors
    qu'avec UNJ, le programme sera compil et on aura comme rsultat la taille
    de cette partie de programme en quartets.

    - ON ou OFF
      Si vous trouvez la compilation trop lente (il faut le faire!), vous pouvez
        activer OFF, ce qui teindra l'cran durant la compilation (et seulement
        durant la compilation), sinon mettez ON.
     - Exit
        Vous sortez du menu d'options
   
    En revenant  mon exemple du dbut, si je mets Hexa, JMP...
       j'aurais comme rsultat 142164808C

3.Les Directives de Compilation
-------------------------------
    Elles sont dclars par un !, ce sont !HP, !PC, !0-15, !1-16, !ON, !OFF.
    Elles ont le mme role que celles employes dans le menu d'options, mis
        part le fait qu'elles peuvent tre utiliss  n'importe quel endroit
          du programme: on peut donc effectuer des mlanges.
    Si vous les mettez dans votre source, elles ont l'avantage d'tre
       indpendantes du Menu d'Options, car prioritaires, on n'a donc pas
          besoin de dclencher OPT  chaque fois.

4.Le Linker
-----------
    C'est un des outils les plus puissants de l'Asm Flash. C'est l'quivalent
    du linker de Turbo C pour les connaisseurs, utilis pour faire des fichiers
    projet. Le but du linker est de pouvoir subdiviser son source  son gr.
    Exemple: 'INITIALISATION
             'GROSSE_BOUCLE
             'FIN_PROG
             @

    Si je compile ce source, l'Asm Flash va compiler le fichier INITIALISATION,
    puis GROSSE_BOUCLE et enfin FIN_PROG. les fichiers links peuvent appeler
    d'autre fichiers car le linkage est rcurrent avec une limite de 25 fichiers
    de profondeur, et c'est largement suffisant, croyez-moi. C'est un vrai
    linker car l'Asm Flash fait lui mme son RCL, et se ballade de fichier
    en fichier: il ne consomme pas de mmoire (si il y a une erreur dans un
    fichier link, vous ne saurez plus ou c'tait, contrairement au Flash)

    Je vous conseille d'utiliser le linker jusqu' puisement, car plus on
       subdivise les programmes, plus ils sont lisibles.
    De plus, si vous travaillez sur ordinateur, vous n'aurez pas besoin
       d'envoyer des fichiers d'une tonne, car gnralement on ne rpare
          qu'une erreur  la fois, donc gnralement, seulement une partie de
          programme et si on subdivise, on n'aura qu' envoyer qu'un petit
          fichier au lieu d'un gros.

5.Les Macros
-----------
    Quand on utilise des donnes dans un programme, on aime bien les voir
      indpendantes du source. C'est ce que permet de faire les Macro.
    Elles servent tout d'abord pour les Clbres Load.Reg, Save.Reg.
    Ceux-ci ont un code connu, donc autant les mettre  part.
    Pour utiliser les macro, vous devez avoir un rpertoire Macro, je rpte
       Macro, comme indiqu dans le message d'erreur. Dans celui-ci vous
          mettrez des chaines de caractres Ascii.
    PAUSE
    Exemple: je mets 8FB9760 H->S dans SAVE.REG (en utilisant la Tools.Lib)
             chaque variable est une Macro, mais attention, tout doit tre en
             Ascii, pas d'hexa, d'ou H->S.
    Ensuite, dans mon prog, je mets /SAVE.REG pour appeler SAVE.REG.
    En fait, le contenu de la Macro est concatn dans le Code, donc les Macro
    sont des sources dj compils, contrairement aux Link.
    De plus, le format ASCII permet d'conomiser de la mmoire.
    Les Macro sont trs utiles quand vous utilisez des Grobs dans un programme
       assembleur.

6.L'Editeur d'Erreur
    Cet editeur est appelable par ED, il permet de rparer les petites erreurs,
      surtout celles de syntaxe. Il est trs utile, car il arrive souvent qu'en
      tapant sur ordinateur, on fasse quelques fautes de syntaxe stupides.
    Exemple: A=DAT0 A          D0=D0+ 19             PC=(A)             @
    Ici, j'ai tap D0=D0+ 19 alors que 19 ne tient pas sur un quartet.
    J'aurais donc une erreur Nibble Expected.
    J'enclenche ED, il suffit alors de modifier D0=D0+ 19 par D0=D0+ 5, et le
       tour est jou. Aprs une erreur, la pile est comme suit:
    5 : Source Initial (String)
    4 : [ Nom du Fichier Link d'ou provient l'erreur si Link ]
    3 : [ Source Foireux, s'il provient d'un link, sinon c'est du source
          initial que provient l'erreur qui est dj dans la pile ]
    2 : System Binary : nombre de caractres qui ont pu tre compils.
    1 : Instruction Foireuse (String)
    Aprs avoir enclench ED, elle sera:
    Si pas de Link, 1 : Source Initial Modifi
             Sinon, 3 : Source Initial (String)
                    2 : 'Nom du Link foireux
                    1 : Source du Link modifi (String)
    Ainsi, si vous voulez modifer le fichier link, il ne vous reste qu'
    faire SWAP STO, et relacez ->ASM car le source initial est dans la pile.

7.Les Messages d'Erreur
-----------------------
    Unknown Instruction    : Instruction inconnue.
    CR Or @ Missing        : Chaque fichier, link ou pas, doit tre termin
                             par un Carriage Return et un Arobas.
    Field Expected         : Champ attendu, comme dans A=A+B A.
    Hexa Expected          : Hexa attendu, comme dans LC 123456.
    Nibble 0-15 Expected   : Quartet 0-15 attendu, comme dans P= 15.
    Nibble 1-16 Expected   : Quartet 1-16 attendu, comme dans P= 16.
    Bad Size               : Mauvaise taille pour une instruction.
    Label Already Declared : Label dj dclar.
    Nonexistent Label      : Label non dclar.
    Jump Too Big           : Saut trop important.
    Nonexistent Macro Dir  : Rpertoire Macro inexistant.
    Invalid Macro          : Macro incorrecte.
    Nonexistent Macro      : Macro inexistante.
    Invalid Link           : Link incorrect.
    Too Much Recursion     : Plus de 25 Link de profondeur.
    PAUSE

8.Les Fonctions Spciales
-------------------------
    Quelquefois, quand on veut inclure de petites constantes hexadcimales
      dans un programme, et qu'on ne veut pas utiliser des Macro, on utilise
          Exemple:              va inclure 123.
    Attention: contrairement aux macro, c'est de l'hexa.
               (normal, sinon, vu que c'est un source, on ne pourrait mettre
                le caractre nul)
    Si vous voulez faire du calcul de label, il existent les instructions*
       GOINA et GOINC, qui  sont des LAHEX et des LCHEX particuliers.
       En effet, ceux-ci doivent tre suivis d'un nom label, de telle sorte
       que A=PC
           GOINC LABEL
           A=A+C A mette dans A l'adresse absolue de LABEL
       ou  C=PC
           GOINA LABEL
           A=A+C A
      Si vous trouvez certaines fonctions superftatoires, vous vous trompez,
    car elles sont toutes utilises dans le source de l'Asm Flash, surtout les
    Link et les Macro.

9.Le Dsassembleur
-------------------
    Il y a peu de choses  en dire. Il accepte 2 types d'argument:
    - 2 Entiers, et dans ce cas 2 : #Adresse de Debut
                                 1 : #Adresse de Fin
    - 1 Code, sans commentaire!
    Il retourne un String, qui contient le source desassembl, avec
     gauche l'adresse, et aprs l'instruction. Il se met automatiquement
    en mode !PC, et !1-16. Ainsi, #0 #20 ASM-> donne:
    00000 P=       4
    00002 GOTO     001BC
    00006 CLRST
    00008 A=C      A
    0000A CDEX     A
    0000C R0=A
    0000F ST=1     15
    00012 GOC      00029
    00015 ?ST=1    16
    00018 GOYES    0001C
    0001A RTNCC
    0001C RSTK=C
    0001E C=ID

  Le Listing est de plus format, ce qui est bien pratique. On pourrait faire
un programme qui transforme cette chaine en chaine compilable pour l'assembleur
(Il suffirait de transformer toutes les adresses utiles genre 001BC en label
en rajoutant un * et un Carriage Return) mais l'intrt me semble douter.
  Ce programme est d'autant plus ais que si sauts il y a, le listing etant
format, il se trouve  un nombre de caractres prcis du dbut de ligne.
  Personnellement, j'ai concu ce programme pour dsassembler la ROM en
particulier, et non pour modifier des programmes assembleurs existant, ce qui
ne m'intresse aucunement.
   
                                                           Phong NGUYEN.
