GuideUtilisateur

Voici une partie des pages paires du guide utilisateur !

ORGAMS 16-01-2016


Prise en main rapide

  • RUN"#BURN" (Il n'y a qu'une version ROM)
  • |ORG puis ESC ou |O pour accèder directement à l'éditeur.
  • CONTROL-I (Import) Permet de lire un source DAMS, Maxam (ASCII) ou TurboAss (export ASCII).
  • CONTROL-1 Pour assembler.
  • ESPACE Pour revenir à l'éditeur.
  • CONTROL-4 Pour cycler parmi les erreurs.
  • CONTROL-S pour sauvegarder. CONTROL-O pour ouvrir.
  • CONTROL-2 Pour assembler & exécuter (attention ENT par défaut en #9000).
  • CONTROL-H Pour aide en ligne, disponible dans l'éditeur, le moniteur et la trace.

Présentation

A l'instar de DAMS, Orgams se décompose en :

  • Éditeur (avec validation à la volée des lignes saisies)
  • Moniteur (aka Monogams)
  • Débogueur (désassemblage, trace pas à pas, etc…)

Orgams est très gourmand, croque la vie à pleines dents, et sa taille s'en ressent. Il occupe 3 ROMs :

  • ORGAMS.ROM : Rom de base à placer de 1 à 15 (ou jusqu'à 31 avec le firmware adéquat).
  • ORGEXT.ROM : Rom d'extension à placer de 1 à 127.
  • MONOGAMS.ROM : Moniteur à placer de 1 à 127.

Plusieurs banks se voient monopolisées (de façon décroissante), la bank de base (bkBase) étant :

  • C7 avec 128k
  • FF avec 512k (autorise la cohabitation avec un RAM-DISK 256k).

Puis bkBase-1 est utilisé pour le miroir système/mémoire de travail.
Le source débute en bkBase-2.

Ci-dessous des captures du moniteur, de l'éditeur et de la trace.

Flux entre modules

Ici, "Exec" représente le programme assemblé en cours d'exécution.

Basic

  • |ORGAMS : va au moniteur en effaçant le source.
  • |ORG, |M : synonymes, va au moniteur sans effacer le source.
  • |O : va à l'éditeur sans effacer le source.

Monitor

  • ESC : Goto Ed
  • commande 'basic' : (Retour) Basic.
  • commande 'Dexp' : Goto Debugueur

Ed

  • CTRL-F2 : Si ok, Goto Exec
  • ESC : Goto Monitor

Exec

  • ret : comme RESTORE (mais la pile doit être valable)
  • RESTORE : restaure système et Goto Ed.
  • BRK / rst #30 / call #be00 : Goto Trace

Débugueur

  • ESC : Goto Monitor
  • CONTROL-ESC : Goto Editeur à la ligne visualisée.
  • J : Goto Exec

Exemple de session de programmation :

  1. Peaufinage d'opcodes via l'éditeur. CONTROL-4 permet d'aller directement sur les erreurs pointées lors de l'assemblage (CONTROL-1).
  2. Plutôt qu'un bête RET, utilisez RESTORE or BRK pour sortir de votre programme.
  3. Sauvegarde du source.
  4. Test par CONTROL-2 : cela assemble le code, puis lance le programme.
  5. Le moniteur permet d'étudier toute la mémoire (excepté la mémoire écran, écrasée par Orgams même).

Editeur

On entre dans l'éditeur par |O depuis le basic, ou avec ESC depuis Monogams.
On en sort avec ESC, en lançant l'assemblage + exécution (CTRL 2), ou encore en appuyant sur l'interrupteur du disjoncteur.

La session en cours persiste à travers les resets, avec vérification de validité du source.

Import

La première chose que vous voudrez faire, c'est écouter 6:33.
La seconde sera d'importer vos anciens sources tout miteux (cf "Rédiger un manuel technique pour les nuls" : créer des "histoires utilisateurs").
Via CONTROL-I, Orgams reconnaît automatiquement les sources DAMS et les sources ASCII (TurboASS, Maxam ou ORGAMS). Les différents ajustements seront fait automatiquement, par exemple :

  • 'nbDots EQU &1000' devient 'nbDots = #1000'
  • 'defs 100,nbCols%3' devient 'FILL 100,nbCols MOD 3'

L'opération est très lente, car une bonne partie du pré-assemblage et résolution des symboles se fait à ce moment.

Différences possibles. !!ATTENTION!!

Expressions arithmétiques modifiées.

Exemple :

  • LD A,pal&#ff+1 ; (pal and #ff) + 1

Devient :

  • LD A,pal AND #ff+1 ; pal and #100

En effet, comme #ff+1 est visuellement groupé, il est calculé à part.
Il faut corriger, au choix :

  • LD A,pal AND #ff + 1 ; Ordre gauche vers droite
  • LD A,[pal AND #ff]+1

Comportement ORG

Quand DAMS assemble avec A2, chaque ORG change le PC ($) mais pas l'adresse de stockage ($$). Cependant ORGAMS ne permet pas ce mode. Pour le reproduire, il faudra explicitement remplacer :

  • (DAMS) ORG dest
  • (ORGAMS) ORG dest,$$

DEFS à 1 paramètre

Le 'DEFS size' de DAMS est remplacé par 'F size', qui aboutit à une erreur de syntaxe.
En effet, 'F' est reconnu comme 'FILL', mais seulement quand suivi de ses 2 paramètres obligatoires.
Avec un seul paramètre, DAMS saute l'espace indiqué sans l'initialiser. Il n'y a pas d'équivalent dans ORGAMS. Il faut donc écrire explicitement 'F size,0' (remplacé automatiquement par 'FILL size,0').

Vérification

Dans Monogams, utilisez la commande X pour comparer le code assemblé avec votre code référence.

Limitations

  • L'édition des lignes est limitée à 72 caractères. Si on vous demande pourquoi, vous direz que vous ne savez pas.

Raccourcis clavier

Les raccourcis clavier sont décrits dans l'aide en ligne (maintenir CONTROL-H).
On s'attarde ici sur les plus sophistiqués.

CTRL + C Affiche le catalogue de la disquette.

CTRL L + str (TAB pour continuer la recherche)

Va directement au prochain label commençant par "str". C'est l'équivalent de la commande 'l' de DAMS, avec les améliorations suivantes :

  • Insensible à la casse
  • Permet d'itérer tous les labels commençant par "str". Il suffit de ré-appuyer CTRL L puis RETURN pour aller au suivant, ou simplement appuyer sur TAB.

CTRL * (TAB pour continuer la recherche)

Va à la prochaine occurence du label sous le curseur (réminiscence VI).
S'il n'y a pas de label sous le curseur, on prend le premier label à partir de cette position, c'est à dire le plus proche à droite(*). S'il n'y a pas de tel label, on prend le plus proche à gauche.

E.g.

fx_dispatch  call routine ; CTRL-* ira à la prochaine occurence de 'fx_dispatch' si le curseur est dessus
                          ; ou à la prochaine occurence de 'routine' dans tous les autres cas.

(*) Pourquoi le label à droite ? Un article publié dans "Psychological Science in the Public Interest" montre une tendance à focaliser sur le label suivant le curseur plutôt que celui le précédant. Cet effet est amplifié si le curseur pointe une instruction (e.g. 'call'), mais inversé quand le cobaye vient de lire un verset du coran.

CTRL Enter

Va à la définition du label sous le curseur.
Si ce dernier est lui même une définition, alors on prend le suivant.
S'il n'y a pas de label sous le curseur, même mécanisme de sélection que pour CONTROL-*

E.g.

fx_dispatch  call display3D     ; CTRL-ENTER ira à 'display3D' quelque soit la position du curseur

L'essayer, c'est l'adopter, comme on dit au Danemark.

CTRL Return

Retourne à position précédente (après CTRL Enter). Cela marche sur 8 niveaux.
Comme je ne suis pas chien (*), je vous donne un truc mnémotechnique : "Enter routine", "Return from routine".

(*) Non pas que les chiens soient mesquins, mais ils écrivent rarement des guides utilisateurs.

CTRL M

Cycle parmi les 8 dernières lignes modifiées. Très pratique, je trouve, après s'être baladé dans le source pour revenir là où on en était.

CTRL P

Colle la dernière ligne supprimée avec CTRL-DEL. Fait office d'UNDO rustique, mais permet aussi de dupliquer une ligne plus rapidement qu'avec les blocs. Dans ce cas, il faut effacer pour mieux ré-insérer !

CTRL F (Find) (TAB pour continuer la recherche)

Recherche texte.

  • Non sensible à la casse
  • Indifférent aux tabulations (contrairement à TurboAss où il faut saisir le nombre d'espaces exact pour rechercher les mnémoniques avec opérandes).
  • Par défaut, recherche exhaustive.
    • Précéder la chaîne à rechercher par un espace si l'on souhaite rechercher seulement en début de mots.
    • Faire suivre la chaîne à rechercher par un espace si l'on souhaite rechercher seulement en fin de mots.
    • Encadrer la chaîne à rechercher par des espaces si l'on souhaite rechercher le mot exact isolément.
    • Dans tous ces cas, l'espace au début et à la fin n'est pas cherché littéralement, comme le montrent les exemples suivant.
v Cherché / Dans source -> OR A LD HL,orang LD HL,cador LD HL,morille+4
"or" * * * *
" or" * *
"or " * *
" or " *

Raccourcis Assembleur

On réserve CONTROL+chiffre pour les raccourcis assembleur (a priori moins nombreux). Ce permet :

  1. D'étendre plus facilement les uns et les autres, sans risque de conflit.
  2. De les mémoriser/utiliser plus efficacement (moins d'interférences cognitives, pour parler comme mon concierge).

CONTROL-1 : Assemble

CONTROL-2 : Assemble+jump

CONTROL-4 : Va à l'erreur d'assemblage suivante.

Ces raccourcis sont réalisables d'une main, libérant l'autre pour fumer un cubain.

Le lancement du programme assemblé se fait sous DI, en connexion RAM standard (&C0) et en remettant SP à C000, avec des valeurs correctes pour le système en AF' et BC'.

Source

Il est pré-assemblé.

  • Facilite la détection des erreurs dès la saisie.
  • Identification du label à l'édition plutôt qu'à l'assemblage : essentiel pour assemblage ultra-rapide.
  • Code beaucoup plus compact.
  • Réduit le besoin de fichier 'objet' (code assemblé muni des infos nécessaires pour le reloger et/ou pour accéder à ses routines).
  • Il reste la possibilité d'importer/exporter une version ASCII.
  • A l'affichage, impose casse (pour les opcodes / directives) et tabulation. C'est aussi un avantage : uniformité du code sans avoir à le formater à la main !

Directives de compilation

Org X [,Y]

Ou comment générer à une adresse Y du code destiné à être exécuté en X.

On distingue :
* pointeur code (pseudo label $), l'adresse où le code est censé s'exécuter (ie $ joue à peu près le rôle de PC)
* pointeur objet (pseudo label $$), l'adresse où le code est stocké par l'assembleur.

Dans le scénario le plus fréquent, les deux coïncident, et l'instruction ORG X permet de changer cette adresse.
Utilisé avec 2 paramètres, ORG fixe $ et $$ séparément.

Le code suivant :

     ORG #1000, #2000
loop JP  loop

générera le code C3 00 10 à l'adresse #2000.

Pour changer uniquement $ :

message byte "Hello dad!",0
      ORG #C000, $$
     ; le code est stocké après message
toto      ;ce label vaut #C000

Pour changer uniquement $$ :

     ORG $, #4000

Alignement mémoire

Pour aligner du code à un multiple donné (typiquement, multiple de #100), on peut le copier lors de l'exécution à une telle adresse. C'est la solution du pauvre. Souvent, on aimerait que le code généré soit déjà aligné.

Il existe deux alternatives :

   [...] ; some code
   ORG $+#ff and #ff00
rout01  ;vaut XX00

   [...] ; some code
   FILL -$ and #ff,0
rout02  ;vaut YY00
   [...]

Limitations

Assembler en 00-3F aboutit à un crash.

BANK n (Attention Buggué !)

La directive BANK n reconfigure la mémoire tel que le ferait un OUT &7fff,n.
Ainsi,

   BANK #C4
   ORG #3F00
   [...]  ; #200 octets de code savoureux

installera le code à cheval sur la RAM et sur "#C4".

Tandis que

   BANK #C2
   ORG #3F00
   [...]

installera le code à cheval sur les banks #C4 et #C5.

Bug connu !

Les connections #C1 et #C3 sont mal gérées.

BYTE et WORD

La commande BYTE accepte chaînes et octets, possiblement mixés :

BYTE 12,"ABC",-1 Encode #0c #41 #42 #43 #ff

Un "BYTE" ou "WORD" sans paramètre incrémente les pointeurs ($ et $$) sans écrire en mémoire.
Trois raisons possibles :

  • Réutiliser la valeur courante en mémoire (eg : paramètre que l'on souhaite conserver d'une exécution à l'autre, même en ré-assemblant le code entre temps).
  • A but de documentation, signaler que la valeur n'a pas besoin d'être initialisée par l'assembleur (eg : variables de toute façon initialisées au run-time).
  • Définir facilement des positions dans une structure. Eg :
         ld a,(ix+pat_flags)    Donne ld a,(ix+2)
         ld e,(ix+pat_value)    Donne ld e,(ix+3)
         ld d,(ix+pat_value+1)  Donne ld d,(ix+4)

          ORG 0
pat_pos   WORD       N'écrit rien à l'adresse 0 !
pat_flags BYTE
pat_value WORD

RESTORE

Rétablit le système, la pile, le niveau d'huile avant de revenir à l'éditeur.
Ainsi, nul besoin de sauvegarder AF' et BC', le vecteur d'interruption en #38, etc…

Labels

  • Sensibles à la casse
  • Pas de limitation dans la taille (le nom des labels n'étant stocké qu'une fois, ne pas hésiter à en choisir des longs)
  • Commence par une lettre, suivi de lettres, chiffres, ou un des caractères suivant "_#'"

Expressions numériques

Vrai gestion du signe

Un step = -1 n'encode pas #ff ou encore #ffff, mais bel et bien -1. Ainsi, LD A,step*step passe sans soucis.
Par conséquent, une erreur concernant un dépassement de capacité indique un vrai problème dans votre programme.

Arithmétique étendue

Les labels peuvent prendre des valeurs signées 24 bits. Autorise par exemple :

ram = #40000 ; yes, 256k

chunksNb = 16 ;
chunkSize = ram/chunksNb ;

Les expressions et résultats temporaires peuvent atteindre 1024 bits.

   ld a,ram*ram/#100000000 ;ok, ça vaut 16

Expressions

  • Pas de priorité des opérateurs

Le séquençage se fait uniquement par espaces et crochets.

  • Exemples :
     LD   a,1+2*3  ; 9  (+ et * effectués dans l'ordre)
     LD   a,1+2 *3 ; 9
     LD   a,1+ 2*3 ; 7  (2*3 forme un groupe isolé, calculé à part avant d'ajouter 1)
     LD   a,1+[2*3] ; 7 Idem, de manière plus classique.
  • Règle simple. Rien à retenir. Visuellement cohérent.

Opérateurs logiques et modulo en toutes lettres (and, xor, or, mod)

Facile à retenir.

Répétition

Une instruction ou un bloc peuvent se voir répétés. Les avantages sont évidents :

  • Plus compact (à lire, à écrire, à stocker)
  • Le nombre de répétitions devient contrôlable par un label.
  • "defs" sous stéroïde :
     16** byte 1,2,3  ; 1,2,3,1,2,3,1,2,3...

Pour une répétition de bloc, le '[' doit se trouver sur la même ligne :

;good
   nblines ** [
       INC b:OUTI
       INC b:OUTI
       EXX
       OUT (c),e:OUT (c),d:OUT (c),0
       EXX
       ]
;bad
   nblines **
     [
     INC b:OUTI
     INC b:OUTI
     EXX
     OUT (c),e:OUT (c),d:OUT (c),0
     EXX
     ]

Bien sûr, tout label à l'intérieur d'un bloc répété plus d'une fois lèvera une erreur (double définition).

Les expressions sont ré-évaluées à chaque itération. Cela facilite la création de tables :

             ORG #9000
rampe3   256** BYTE ($*3) and #ff    ; stocke 00 03 06 09 ... FF 02 05 08 ...

Warning !

     4**LD A,(DE):INC E   ; buggy. Only 1 INC E
     4**[LD A,(DE):INC E] ; ok.

On autorise jusqu'à 8 niveaux d'imbrication. Au-delà, demander dérogation à la clinique la plus proche.

Pseudo labels #, ##, ###

Le pseudo label # vaut l'index de l'itération contenante (on compte à partir de 0).
Le pseudo label ## vaut l'index de l'itération au niveau immédiatement supérieur (quand plusieurs répétitions imbriquées, bien sûr).
Etc.

 2 ** [
 3 ** BYTE &10*## + #  ; stocke 00 01 02 10 11 12
      ]

Séparateur ":"

  • Permet de regrouper des instructions qui forment une opération logique, et de mieux figurer les similitudes. Eg :
        LD  hl,awesomeness:inc (hl)
        LD  hl,brightness :inc (hl)
        LD  hl,ovlness    :inc (hl)
  • Moins de ligne = meilleure vue d'ensemble sur une routine.
  • Essentiel pour pseudo-labels à venir.

Assemblage conditionnel

Orgams permet 8 niveaux de IF ELSE END. A consommer sans modération, avec modération.

Points d'arrêt.

La ROM installe au reset une routine de point d'arrêt en #BE00, et un saut vers cette routine en #30.

Appel

Ainsi un RST 6 saute dans le moniteur en mode trace. Du reste, la pseudo instruction BRK (CTRL+SPACE) dans un source émet simplement un RST 6.
L'appel en #BE00 facilite les arrêts conditionnels. Eg :

break = #BE00
    [...]
    LD a,(pattern_pos)  ;Must be non-zero
    OR a
    CALL z,break  ;Investigate !

Tous les registres au moment de l'arrêt sont préservés. La seule manipulation destructive est l'écriture de 2 mots dans la pile :

  1. L'adresse de retour placée par le RST (ou le CALL #BE00), nécessaire pour connaître le PC courant.
  2. Un PUSH AF nécessaire pour sonder IFF (état EI/DI).

Dans une utilisation classique, cela ne perturbe en rien le retour dans le programme (à l'instar d'une interruption). Mais si SP pointait sur une table, il faudra tenir compte de la corruption des 4 octets.

Il faudra veiller vous-même à la connexion RAM avant d'utiliser BRK !
Exemple de piège :

   LD  BC,#7fC2
   OUT  (C),C
   [...]
   BRK     ; Plantage !! Saute en #30 dans la mauvaise banque.

Débuggueur/Désassembleur.

On distingue deux types de navigations, avec ou sans exécution. Du reste, la commande 'd' du moniteur peut se comprendre (D)ebug ou (D)ésassemble.

Sans exécution, il s'agit d'un désassemblage classique, mais avec toute la souplesse Orgams (embrasse tes genoux) :

  • scrolling haut et bas (rapide avec CONTROL)
  • CONTROL-ENTER et RETURN à l'instar de l'éditeur pour explorer des sous-routines (et en revenir !) sans avoir à saisir une seule adresse.

Avec exécution, on retrouve tout la puissance d'un débuggueur pas à pas :

  • (S)tep exécute une instruction. S'il s'agit d'un appel, on entre dans la sous-routine.
  • (N)ext exécute en mode rapide
  • Parfois, on ne veut ni tracer ni même exécuter une routine (e.g. #BB06). Dans ce cas, il suffit de placer le pointeur à l'instruction suivante, et de ses doigts activer CONTROL-G. Cela replace PC ($) sans rien exécuter.
  • Pour ne pas avoir à suivre laborieusement les N itérations d'une boucle, on placera le curseur de façon adéquate, puis on appuiera sur T ou ESPACE : la boucle sera bien exécutée, mais en mode rapide.

Limitations émulation :

  • Les bit 3 & 5 du registre F ne sont pas correctement reproduits.
  • Les interruptions ne sont pas émulées.

Visualisation Source/Mémoire :

Orgams tâche de retrouver la ligne du source correspondant à l'opcode sous le curseur '>'. Il peut échouer, à tord ou à raison, affichant alors "source not found". Cette fonctionnalité ralentit la trace pas à pas, surtout en cas d'échec.
Une légère pression sur CONTROL-V permet de basculer vers un dump mémoire, à la dernière adresse sélectionnée par la commande 'M' du moniteur. Ce mode là ne pénalise pas la trace en vitesse.

Retour au source

CONTROL-ESC retourne à l'éditeur à la ligne en cours de visualisation, contrairement à ESC-ESC qui ne touche pas au curseur d'édition.

Retour au programme.

Le retour se fait par J (comme JUMP). L'état du Z80 est restauré : du point de vue des registres tout se passe comme si on avait appelé la routine PUSH AF:POP AF:RET. Bien sûr si le programme a été tracé pas à pas, on reprend avec les valeurs courantes de registres.
Les registres CTRC sont rétablis avec les défauts système.

Sauf mention contraire, le contenu de cette page est protégé par la licence Creative Commons Attribution-ShareAlike 3.0 License