GuideUtilisateur
Table des matières

Voici une partie des pages paires du guide utilisateur !


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).
  • Ou: * CONTROL-O pour ouvrir un fichier d'exemple ("3d.o").
  • CONTROL-1 Pour assembler.
  • ESPACE Pour revenir à l'éditeur.
  • CONTROL-4 Pour cycler parmi les erreurs.
  • CONTROL-S pour sauvegarder.
  • 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 4 ROMs (depuis la version EE):

  • 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.
  • BRICBRAC.ROM : Extension à placer de 1 à 127 (ou 1 à 15 pour installer la RSX |BURN). Depuis version EE

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).

Les 4 premières banks sont prises entièrement:

  • bkBase: Housekeeping et autres buffers internes.
  • bkBase-1: Miroir système/mémoire de travail.
  • bkBase-2: Réservée pour miroir page &c000 (mais non exploité maintenant, purement gaché)
  • bkBase-3: Début source

Cela signifie qu'avec 128k (CPC stock + ROMs), il y a moins de 16k disponible pour le source, et seulement les 64k de base pour le programme (cela dit, toute cette mémoire est utilisable, y compris les zones systèmes, sans que cela perturbe Orgams).
Si cela est trop juste, rabattez-vous sur la version Demomaker'sDelight.

Philosophie

Orgams tend vers une transparence totale, à l'instar de la Multiface II et des outils sur émulateur :
* Toute la mémoire est analysable (sauf la page C000: Todo #62 & 67).
* Le Z80 est émulé en mode trace pour un contrôle total. Caveat emptor: l'émulation n'est pas parfaite (bits 3 & 5 du registre F), les autres composants ne sont pas émulés.

Cela a des implications pratiques. Si vous programme modifie le firmware, cette modification ne se verra pas reportée lors d'un retour au basic. Etant donné que la page &8000 est complètement à disposition de votre programme, le firmware est ré-installé à la sortie d'Orgams.

RSX

|ORGAMS :

/!\ Supprime tous les sources et saute à monogames (le moniteur)
Vous ne devriez jamais avoir à l'utiliser, sauf si la mémoire a été corrompue.

|ORG, |M, |OM

Saute à monogames.

|ORG,bank

Installe Orgams dans une autre banque (C7, CF, D7, DF …).
Vous ne devriez jamais avoir à l'utiliser. Uniquement destiné à des fins de débogage privé (plusieurs orgams en une journée).

|O, |OE

Saute à l'éditeur.

|O, "fichier" |OE, "fichier"

Charge le "fichier" (".o" ajouté s'il n'y a pas d'extension) dans le premier onglet libre, ou dans l'onglet 9 si aucun n'est libre, et saute à l'éditeur.
Si l'onglet 9 contient un source non sauvegardée, il est proposé de le sauvegarder (N pour ignorer la sauvegarde, ESC pour annuler toute l'opération).
Equivalent à : |ORGLOAD, "fichier":|O

|ORGLOAD, "fichier",tab

Charge le "fichier" dans l'onglet indiqué (ou premier onglet libre si le paramètre tab est omis) et revient au BASIC.
Encore une fois, cela n'écrasera pas un source non sauvegardé.

|ORGRESET

Efface tous les sources (propose de sauvegarder ceux qui ont été modifiés).
Très utile pour créer un espace de travail propre :

10 |ORGRESET
20 |ORGLOAD, "journal",5
30 |ORGLOAD, "ply",2
40 |O, "plynrt"

|TR,address,rom

Sauter à la trace à la rom et à l'adresse indiquées. Les deux paramètres sont facultatifs

Flux entre modules

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

Basic
Voir la section RSX.
On vérifiée que le source actuel n'a pas été écrasé, ce peut se produire lors de l'utilisation d'autres outils. Par exemple, Parados effectuant un test destructif de la mémoire.

Monitor

  • ESC : Goto Ed
  • Control-B : 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ébogueur

  • 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).

(*) Même avec un simple RET, Orgams restaure le système. Nul besoin de sauvegarder les registres secondaires, le saut en &38, ou quoi que ce soit.

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.

SHIFT CLR

Efface tout en partant du curseur (comme si vous appuyiez sur CLR tel un malade).

SHIFT DEL erase all before cursor

Efface tout précédant le curseur.

CTRL DEL

Efface toute la ligne.

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, comme \b en syntaxe regex.
    • 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 " *

CTRL-% (CTRL-+ sur QWERTY) Parcourir IF-ELSE-END MACRO-ENDM [-]

Si le curseur pointe sur IF, ce raccourci passe au ELSE (s'il existe) ou au END correspondant.
Et vice versa.
Il en va de même pour les macros et les blocs de répétition.
S'il est utilisé sur une ligne sans aucune de ces directives, il passera à la suivante.

CTRL-B + touche : Enregistre un signet à la ligne actuelle.

Un maximum de 16 signets est mémorisé (et stocké dans un fichier .o).

SHIFT-CONTROL + touche :Aller au signet correspondant.

Puis CONTROL-RETURN permet de revenir à l'endroit où l'on se trouvait.

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
   [...]

Bug connu

Le code assemblé en &30-&32 se voit écrasé par JP &BE00 (mécanisme breakpoint).

ALIGN(n) (example MACRO)

Avance $ au plus proche multiple de n.
Si $ est déjà un multiple de n, la directive est sans effet.

NB: $$ est incrémenté de la même valeur.

ALIGN n'est pas une directive intégrée, et peut être simulée par :

  MACRO ALIGN n
    SKIP -$ MOD n
  ENDM

Explication :
On veut sauter x octets tels que $+x = 0 [n] et 0 <= x < n
Cela revient à x = -$ MOD n

ASSERT(prédicat) (exemple MACRO)

Provoque une erreur d'assemblage si le prédicat est faux (0 en pratique).

ASSERT n'est pas une directive intégrée. Elle peut être simulée par :

  MACRO ASSERT predicate
    IF predicate:ELSE
   !! ERROR !!
  END
  ENDM

Explication:
La line '!! ERROR !!' n'est pas assemblée du tout si le prédicat est vrai, et provoque une erreur sinon.

Exemple 2:

  MACRO ASSERT_NOT predicate
    IF predicate
 !! ERROR !!
    END
  ENDM

  [...]

  ASSERT_NOT (my_table AND &ff) ; Garantie que my_table est de la forme xx00

Limitation

La ligne d'erreur pointe sur le corps de la macro, pas sur son invocation.
Ce n'est guère pratique.

LIMIT n

Pas de telle direction pour l'instant, la solution du pauvre :

Ajouter en fin de code :

  SKIP &A000-$  ; To protect overlapping at &A000

Explication:
Si $ est supérieur à &A000, la valeur est négative, provoquant une erreur.

BANK n (Attention Buggué pour &C1 et &C3 !)

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.

Bugs connu !

  • Les connections #C1 et #C3 sont mal gérées.
  • La sauvegarde binaire enregistre ce qu'il y a en bank &C0 (bug #DA).

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

STR

Pas de telle directive comme sous MaxaM, émulée par :

     BYTE "Piou!" OR &80

N'importe quelle opération logique ou arithmétique est utilisable, elle sera appliquée au dernier octet de la chaîne.

SKIP n

Equivalent à n ** BYTE.
C'est à dire que $ et $$ sont incrémentés de n, sans écriture mémoire.

RESTORE

Rétablit le système, la pile, le niveau d'huile avant de revenir à l'éditeur.
Nul besoin de sauvegarder AF' et BC', le vecteur d'interruption en #38, etc…
Cette dernière remarque est aussi valable pour un simple RET, pour peu que la pile soit valide.

IF ELSE END

Assemblage conditionnel:

IF predicate
   [...]  // Assemblé si prédicat différent de 0
END

; Autre exemple
IF toto-4 
   [...]  // Assemblé si toto != 4
END

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

MACRO

La définition doit précéder l'usage.

Définition d'une macro

MACRO macro_name [param1[,param2[,...]]]
...
ENDM

Copié du manuel de Rasm:
Une macro est une façon d’étendre le langage, en définissant un bloc d’instructions, délimité par MACRO
et ENDM, et qui pourra être inséré ultérieurement dans le code, par simple utilisation du nom
de la macro. Les macros peuvent prendre des paramètres, il est ainsi possible de faire de l’assemblage
conditionnel avec les macros : à chaque appel de macro, le code d’origine est inséré, avec substitution
des paramètres.

Exemple classique :

MACRO SET_CRTC reg, val
     ld bc,&bc00+reg:out (c),c
     ld bc,&bd00+val:out (c),c
  ENDM

Utilisation d’une macro

Reprenant l'exemple précédent:

     SET_CTRC 1,48

Attention ! Orgasm pense que vous voulez déclarer un label si vous tentez d'invoquer une macro sans paramètre.
Pour palier à ce défaut, ajoutez une paire de parenthèse "()".

MACRO DBG_MARKER
  IF debug
    push af
    push bc
    ld bc,&7f10:out (c),c
    ld a,r:and &1f:or &40:out (c),a
    pop bc
    pop af
  END
ENDD
...
    DBG_MARKER () ; explicit invocation of macro

Appel de macro avec paramètres dynamiques

Les paramètres passés lors de l’appel d’une macro ne sont pas nécessairement des constantes, ils peuvent être des expressions :

MACRO RWORD w
  ; Reversed word (Big endian).
  BYTE w/&100, w and &ff
MEND

   3 ** RWORD #+2  ; Produce 00,02,00,03,00,04

Limitations

En l'absence de labels locaux ou auto-numérotés, déclarer un label dans une MACRO aboutit à une erreur d'assemblage (multiple définition).
Cela restreint passablement l'utilité des MACROs, et sera comblé dans une prochaine version d'Orgams.

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

La recette suivante est appliquée :

  • Restore firmware (00-3F et HIMEM-BFFF)
  • Restore breakpoints (30-32 et BE00-BE??) (actually these two steps are done under the hood when returning to Orgams, leading to bug #e2)
  • Assemble
  • Restore firmware's SP (BFD0 et des brouettes)
  • Push housekeeping routine on the stack
  • Connection C0, désactive ROMs basse et haute, DI
  • Saute à l'adresse d'exécution (CONTROL-2).

Monogams

N'hésitez pas à utiliser les flèches pour naviguer dans l'historique.
Quelques commandes notables :

d[nn]

Désassemblage.

  • d: Va à la dernier adresse visité (pointeur >)
  • dnn: Visite à partir de nn

t[nn]

Comme d, avec les nuance suivante:

  • t: Va au prochain opcode à exécuter (pointeur $)
  • tnn: Change PC ($) afin de tracer à partir de nn.

NB:

  • Cela correspond à la commande t de DAMS.
  • t équivaut à d puis CLR.

m[nn]

Dump mémoire à partir de nn. Si rien n'est spécifié, utilise la précédente adresse.
Les octets sont affichées en hexa, ASCII et graphiquement. Pratique pour vérifier une courbe ou détecter des anomalies.
Les zones à 0 sont sautées. Merci qui ?

xnn,nn2

Compare deux zones mémoires. Seules les différences sont affichées.
Ainsi, pour comparer par exemple les banks &c6 et &c7:

b&c2
x&8000,&c000

hnn,size

Injecte 'size' octets à partir de 'nn' dans le source sous forme de BYTE.

gr

Dump graphique de la mémoire.
Attention contrairement au Hackeur, on n'obtient pas 1 octet non nul = 1 pixel mis.
Les octets sont grosso-modo ORés par paquets de 8.

clear[n] / clr[n]

Rempli les 128 premier ko avec n ou 0, indépendamment de la connexion courante.

clearpage[n] / clp[n]

Rempli la page connectée (64 ko) avec n ou 0.

Points d'arrêt.

Quand Orgams est invoqué puis à chaque assemblage, une routine de point d'arrêt est installée en &BE00, et un saut vers cette routine en &30.

Appel

Ainsi un RST 6 bascule 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).

Limitations

  • Dans une utilisation classique, l'écriture dans la pile (voir ci-dessus) 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.
  • Orgams tente de détecter la connexion bank (MMR) au moment du BRK. La méthode est heuristique et faillible.

La connexion ROM (RMR) n'est pas détectée. C'est un bug.

BreakPoint soft.

Il est possible d'utiliser la trace rapide pour breaker sans modification du code (en ROM par exemple).

  • $start pour placer le PC sur le code à exécuter. Sortir de la trace par ESC.
  • dbreak pour se placer sur l'adresse du breakpoint, puis espace ou t(trace rapide jusque ce que $ atteigne >).

Par exemple, si l'adresse d'entrée de votre programme est &9000, et que vous voulez interrompre en &BB5A:

  • $&9000, ESC, d&bb5A, space.

Pour ce cas de figure il peut être plus efficace de modifier le source!

   ORG &BB5A:BRK
   ORG &9000:ENT $

Limitations

En mode trace, tout le CPC n'est pas émulé: pas d'interruptions, pas de clavier, …

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 (ou flèche droite) et RETURN (ou flèche gauche) à 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", notamment si le source n'est pas monotone (e.g. ORG &1000 après ORG &9000).

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.

Possible échec

Le retour peut échouer dans les cas suivants :

  • Il y avait du code en page C000 (écrasé par l'affichage de la trace).
  • SP pointait sur une table.
  • La connexion ROM/RAM est erronée.

Problemes connus.

Ci-suit les bugs connus pour ErogenousEmpowerment releases.
Pour les bugs introduits par la version de travail FF, consulter la section Regression dans working.
Cliquez bugs pour amples descriptions.

See UserGuide

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