ORGAMS 29 Juin 2019 ------------------- ::::::::::::::: : Quick Start : :::::::::::::::  - RUN "#BURN" (to install ROMs.)  - |ORG then ESC, or |O to go directly to the editor.  - CONTROL-I (Import)� Loads� a� DAMS� source� file,� Maxam (ASCII) or  èTurboAss (exported to ASCII).  - CONTROL-1 To assemble.  - SPACE To return to the editor.  - CONTROL-4 To cycle through the current errors.  - CONTROL-S to save. CONTROL-O to open.  - CONTROL-2 To assemble & run (warning default ENT is &9000).  - CONTROL-H For online help,� available� in� the editor, monitor, and  èdebugger. :::::::::::: : Overview : :::::::::::: Like DAMS Orgams breaks down into:  - Editor (with validation on the fly lines seizures)  - Monitor (aka "Monogams")  - Debugger (disassembly, trace step-by-step, etc ...) Orgams is large although heavily crunched it occupies 3 ROMs:  - ORGAMS.ROM: Base Rom place in any rom position 1 to 15 (or up to 31  èwith the proper firmware).  - ORGEXT.ROM: Expansion Rom placed at any rom position 1-127.  - MONOGAMS.ROM: Monitor placed at any rom position 1-127. Several banks� are� being� used� (decreasingly),� basic� bank (bkBase)  èbeing:  - C7 with 128k  - FF with 512k (allows cohabitation with 256k RAM-DISK). Then bkBase-1 is used for the mirror system / working memory. The source begins in bkBase-2. :::::::::::::::::::::::: : Flow between modules : :::::::::::::::::::::::: Here, "**Exec**" represents the assembled program running.  **Basic**  - |ORGAMS: opens the monitor and deletes the source code.  - |ORG, |M: opens the monitor without deleting the source code.  - |O: opens the editor without deleting the source code.  **Monitor**  - ESC: Goto **Ed**  - Order 'basic': (Back) Basic.  - Command 'DEXP' Goto **debugger**  **Ed**  - CTRL-F2: If ok, Goto **Exec**  - ESC: Goto **Monitor**  **Exec**  - ''RET'': as RESTORE (but the battery must be valid)  - ''RESTORE'' Restores system and Goto **Ed**.  - ''BRK / rst &30 / call &BE00'': Goto **Trace**  **Debugger**  - CONTROL-ESC: Goto **Editor** to visualized line.  - ESC: Goto **Monitor**  - J: Goto **Exec** Programming session example:  - Tweaking opcodes via the editor.� CONTROL-4 makes it possible to go  èdirectly to the reported errors during assembly (CONTROL-1).  - Rather than a mere RET,� use� RESTORE� or� BRK� to quit out of your  èprogram.  - Save source.  - Test by CONTROL-2: it assembles the code and run the program.  - The monitor allows to� study� all� memory (except the screen memory  èthis is used by Orgams' display). :::::::::: : Editor : :::::::::: Enter the editor using� |O� from� BASIC,� or� by� pressing� ESC in the  èMonitor. Leave� the� editor� by� either� pressing� ESC,� launching� assembly� +  èexecution (CTRL 2), or by resetting the CPC. The current session persists across� resets,� with the source validity  ècheck. Import ###### The first thing you want to do is listen 6:33. The second will be to� import� your� old� tatty� sources (see "Write a  ètechnical manual for Dummies", how to create "user stories"). Via CONTROL-I, Orgams automatically� recognizes� source� from DAMS and  èother ASCII sources (TurboASS, Maxam or ORGAMS). The various adjustments will be made automatically for example:  - 'NbDots EQU &1000' becomes 'nbDots = &1000'  - 'Defs 100,nbCols%3' becomes 'FILL 100,nbCols MOD 3' The operation is very slow because much of the pre-assembly and symbol  èresolution is done at this time. Possible differences. **!!WARNING!!** =====================================  Modified Arithmetic. --------------------- Example:  - LD A, pal&#ff+1; (pal and #FF) + 1 Becomes:  - LD A, pal AND &FF+1; pal and &100 Indeed, as &ff+1� is� visually� grouped,� it� is� therefore calculated  èseparately. It must be corrected to either of these:  - LD A, pal AND &FF + 1; Direction left to right  - LD A, [pal AND &FF]+1  ORG behavior ------------- When DAMS assemble with A2, each� ORG� changes� the PC ($) but not the  èstorage address ($$). However ORGAMS does not allow� this� mode.� To� reproduce� the� same� action� it� must� be  èexplicitly replaced:  - (DAMS) ORG dest  - (ORGAMS) ORG dest, $$  1 parameter DEFS ----------------- The 'DEFS size' DAMS is replaced� by� 'F� size', resulting in a syntax  èerror. Indeed, 'F'� is� known� as� 'FILL',� but� only� when� followed� by two  èmandatory parameters. With one parameter, DAMS reserves space without initializing it. There  èis no equivalent in ORGAMS. We must therefore explicitly write� 'F� size,� 0'� (automatically� replaced by  è'FILL size, 0'). Checking ======== In Monogams, use the X command to compare the assembled code with your  èreferral code. Limitations ###########  - Editing of lines is� limited� to� 72� characters. If asked why, you  èwill say that you do not know. Hotkeys ####### Keyboard shortcuts are described in the online help (press CONTROL-H). We concentrate here on more sophisticated. CTRL + C Displays the catalog of the disk. ========================================== CTRL + L **str** (TAB to continue the search) ============================================= Go directly to the next label beginning with "str". This is equivalent  èto the command 'the DAMS, with the following improvements:  - Insensitive to breakage  - You can iterate all labels� beginning with "str". Just press CTRL-L  èagain then RETURN to move to the next or just press TAB. CTRL * (TAB to continue the search) =================================== Go to the next occurrence of the label under cursor (reminiscent VI). If there is no label under cursor,� it takes the first label from this  èposition(*). If there is no such� label,� it� takes the closest to the  èleft. E.g. fx_dispatch call� routine;� CTRL-*� will� go� to� next� occurrence� of  è'fx_dispatch' if the cursor is over                           ; or next� occurrence� of� 'routine'� in all  èother cases. (*) Why the label to the right? An article published in "Psychological  èScience in the Public Interest" shows a tendency to focus on the label  èfollowing the cursor rather than the� one preceding it. This effect is  èamplified if the cursor is an� instr uction (e.g. 'call'), but reversed  èwhen the guinea pig just read a verse from the Koran. CTRL Enter ========== Go to the definition of the label under the cursor. If the latter is itself a definition, then we take the next. If there is no label under� the� cursor, same selection mechanism than  èCONTROL- * E.g. fx_dispatch call display3D ; CTRL-ENTER go to 'display3D' whatever the  ècursor position To try it is to adopt, as we say in Denmark. CTRL Return =========== Back to previous position (after Ctrl Enter). It works on 8 levels. As I am not dog (*), I� give� you a mnemonic: "Enter routine", "Return  èfrom routine." (*) Not that dogs be petty, but they seldom write user guides. CTRL M ====== Cycle through the last� 8� rows� changed.� Very� handy, I find, having  èwandered in the source to return to where it was. CTRL P ====== Paste the last line cut� with� CTRL-DEL.� UNDO� serves rustic but also  èallows you to duplicate a line� faster� than the blocks. In this case,  èmust be deleted to better re-insert! CTRL F (Find) (TAB to continue the search) ========================================== Text Search.  - Case insensitive  - Indifferent to the tabs� (unlike� TurboAss� where you have to enter  èthe exact number of spaces to search mnemonics with operands).  - By default, exhaustive search.  * Precede the search string with a� space� if it is desired to search  èonly at the beginning of words.  * End the search string with a� space� if� one wishes to look only at  èthe end of words.  * Surround the search string with spaces if you want exact search for  èthe word alone.  * In all these cases, the space� at� the� beginning and at the end is  ènot wanted literally. Assembler Shortcuts ################### We reserve CONTROL+number for� assembler shortcuts (presumably fewer).  èThis allows:  - Expand easier each other without risk of conflict.  - From store / used more efficiently (less cognitive interference, to  èspeak like my concierge). **CONTROL-1**: Assemble ======================= **CONTROL-2**: Assemble+jump ============================ **CONTROL-4**: Go to the next assembly error. ============================================= These shortcuts are achievable� with� one� hand,� freeing the other to  èsmoke a Cuban. Program is lunched under DI, standard� RAM connection (&C0), SP set to  èSP C000, with the correct firmware values for AF 'and BC'. :::::::::: : Source : :::::::::: It is pre-assembled.  - Facilitates the detection of errors when typing.  - Identification of the label� rather� than� to editing the assembly:  èessential for super-fast assembly.  - Much more compact code.  - Reduces the need for� file� 'object'� (assembled code provided with  èthe information necessary for the� relocation� and� / or to access its  èroutines).  - There is the possibility to import / export ASCII versions.  - In the display,� imposes� breaks� (for� opcodes / instructions) and  èTab. It is also an� advantage:� uniformity� of� code without having to  èformat it by hand! Compiler directives ################### Org X [,Y] ========== Or how to generate a Y address of the code to be executed by X. We distinguish:   * Code pointer (pseudo� label� $),� the� address� where� the code is  èsupposed to run (ie $ almost plays the role of PC)   * Object pointer (pseudo label� $$),� the� address where the code is  èstored by the assembler. In the most common� scenario,� the� two� coincide,� and� the ''ORG X''  èallows to change this address. Used with two parameters fixed ORG $ and $$ separately. The following code:      ORG &1000, &2000 loop JP loop generate the code ''C3 00 10'' at &2000. To change $ only: byte message "Hello dad!", 0       ORG &C000, $$      ; the code is stored after post toto; this label is &C000 To change $$ only:      ORG $,&4000  Known bugs ----------- Assembled code in� &30-&32� is� overwritten� by� JP� &BE00 (Breakpoint  èmechanism). ALIGN(n)  (MACRO example) ========================= Advance $ to the closest multiple of n. If $� is� already� a� multiple� if� n,� the� directive� doesn't change  èanything. NB: $$ is incremented by the same amount There is no ALIGN directive. It can be simulated by:   MACRO ALIGN n     SKIP -$ MOD n   ENDM Explanation:   We want to skip x bytes such that ''$+x = 0 [n]'' and ''0 <= x < n''   This amounts to ''x = -$ MOD n'' ASSERT(predicate)   (MACRO example) =================================== Raise an error if predicate isn't true. There is no ASSERT directive. It can be simulated by:   MACRO ASSERT predicate     IF predicate:ELSE    !! ERROR !!   END   ENDM Explanation:   The '!! ERROR !!' part is not seen at all if predicate is true,   otherwise it triggers an assembly error. Example 2:   MACRO ASSERT_NOT predicate     IF predicate  !! ERROR !!     END   ENDM   [...]   ASSERT_NOT (my_table AND &ff) ; Ensure my_table is &100 aligned  Caveat -------   Currently the error line� points� to� the� macro� definition, not to  èmacro invocation.   That's unconvenient. LIMIT n ======= No such directive for now, but here is a workaround: After your code, add:   SKIP &A000-$  ; To protect overlapping at &A000 Explanation:   If $ if greater than &A000, the value is negative, raise an error. BANK n ====== Directive� BANK� n� re-configures�� the�� memory� similarly� to� ''OUT  è&7FFF,n''. So,    BANK &C4    ORG &3F00    [...]; &200 bytes of tasty code generates code both in main RAM and "&C4". While    BANK &C2    ORG &3F00    [...] generates code both in banks &C4 and &C5.  Known bug! ----------- The connections &C1 and &C3 are poorly managed. BYTE and WORD ============= The BYTE command accepts strings and bytes, possibly mixed:     ''BYTE 12,"ABC",-1 Encodes 0c 41 42 43 ff'' A "BYTE" or "WORD"� without� a� value� increments� pointers ($ and $$)  èwithout writing into memory. Three possible use-cases:  - Reuse the current value� in� memory� (eg:� setting that you want to  èkeep from one� run� to� another,� even� in� the� code re-assembling in  èbetween).  - A purpose of documentation, note that the value does not need to be  èinitialized by the assembler (eg:� variable anyway initialized at run- ètime).  - Easily define positions in a structure. Eg:          ld a, (ix + pat_flags) Give ld a, (ix + 2)          ld e, (ix + pat_value) Give ld e, (ix + 3)          ld d, (ix + pat_value + 1) Give ld d, (ix + 4)           ORG 0 pat_pos WORD       ; Do not write anything at 0! pat_flags BYTE pat_value WORD RESTORE ======= Restore the system, the battery, the oil level before returning to the  èeditor. Thus, no need to save AF� 'and� BC',� the interrupt vector in &38, etc  è... Labels ######  - Automatically detects invalid references  - No limitation in size (the name of labels being stored once, do not  èhesitate to choose long)  - Starts� with� a� letter,� followed� by� letters,� numbers,� or� the  èfollowing characters "_ #" Digital Expressions ################### True management sign ==================== A ''step = -1'' does not encode� ''&ff'' nor ''&ffff'', but indeed -1.  èThus, ''LD A, step*step'' passes without worries. Therefore, an error in an� overflow� indicates� a real problem in your  èprogram. Extended Arithmetic =================== Labels can take the signed 24-bit values. Authorizes for instance: ram = &40000; yes, 256k chunksNb = 16; chunkSize = ram / chunksNb; Expressions and temporary results can reach 1024 bits.    ld, ram*ram / &100000000; ok, it's 16 Expressions ===========  - Warning: No operator precedence! Sequencing is made only by spaces and square brackets.  - Examples:      LD,1+2*3; 9 (+ and * made in order)      LD,1+2 *3; 9      LD,1+ 2*3; 7 (2 * 3 form an isolated group, calculated separately  èbefore adding 1)      LD 1+[2*3]; 7 Idem, more classic.  - Simple rule. Nothing to remember. Visually consistent. Logical operators and modulo in full (and, xor, or, mod) ========================================================  Easy to remember. Repeat ###### An instruction or a block can be repeated. The advantages are obvious:  - Compact Plus (to read, write and store)  - The number of repetitions is controlled by a label.  - "Defs" on steroids:      16 ** byte 1,2,3; 1,2,3,1,2,3,1,2,3 ... For a block repetition, '[' should be on the same line: ; 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      ] Of course, any label within a block repeated more than once will throw  èan error (double definition). Expressions are re-evaluated at� each� iteration. This facilitates the  ècreation of tables:              ORG &9000 rampe3 256 ** BYTE $*3 and &FF ;� stores� 00� 03 06 09 ... FF 02 05 08  è... Warning!      4 ** LD A, (DE): INC E; buggy. Only 1 E INC      4 ** [LD A, (DE): INC E]; OK. It allows up to 8 levels of� nesting. For more, request exemption from  èthe nearest clinic. Pseudo labels #,  ##, ### ========================= The pseudo label # is the� index� to the containing iteration (include  èfrom 0). The pseudo label ## is the� index� of� the iteration at the next level  è(when several nested repetition, of course). Etc.  2 ** [  3 ** BYTE &10*## + # ; stores 00 01 02 10 11 12       ] Separator ":" #############  - Used to group instructions� that� form� a logical operation, and to  èbetter include the similarities. Eg:         LD hl, awesomeness: inc (hl)         LD hl, brightness : inc (hl)         LD hl, ovlness    : inc (hl)  - Less line = better overview on a routine.  - Essential for coming pseudo-labels. Conditional assembly #################### Orgams allows 8 levels of IF� ELSE END. To consume without moderation,  èwith moderation. :::::::::::::::: : Breakpoints. : :::::::::::::::: ROM installs to reset a breakpoint routine &BE00, and a jump to &30 in  èthis routine. Call #### Use RST 6 to jump� into� the� monitor� in trace mode. Identically, the  èpseudo BRK instruction (CTRL + SPACE) in the source simply puts RST 6. Using call &BE00 facilitates conditional stoppages. Eg: break = &BE00     [...]     LD (pattern_pos) ; Must be non-zero     OR a     CALL z,break; Investigate! All registers at the� time� of� the� judgment� are preserved. The only  èdestructive manipulation is writing two words in the stack:  - The return address placed by the� RST (or CALL &BE00), necessary to  èknow the current PC.  - One PUSH AF necessary to probe IFF (state EI / DI). In conventional use, this does not� disturb� the return to the program  è(like an interrupt). But� if� SP� pointed� to� a� table,� it will take  èaccount of the corruption of 4 bytes. Make sure you restore the RAM banks before using BRK! Example trap:    LD BC, &7fC2    OUT (C), C    [...]    BRK; Crash !! Jumps to &30 in the wrong bank. :::::::::::::::::::::::::::: : Debugger / disassembler. : :::::::::::::::::::::::::::: There are two types of navigation, with or without execution. Besides,  èthe� command� 'of�� the�� monitor�� can�� be�� understood� (D)ebug� or  è(D)isassemble. Without enforcement, this is a� classic� disassembly, but with all the  èflexibility Orgams (kiss your lap):  - Up and down scrolling (fast with CONTROL)  - CONTROL-ENTER and RETURN� like� the� editor� to explore subroutines  è(and back!) Without having to enter a single address. With execution include all the power of a debugger step by step:  - (S)tep executes an instruction. If� there� is a call, it enters the  èsubroutine.  - (N)ext running in fast mode  - Sometimes you neither� want� to� trace� nor� execute� a routine (eg  è&BB06). In this case, simply move the pointer to the next instruction,  èand fingers enable CONTROL-G.� This� changes� PC ($) without executing  èanything.  - To avoid having to painstakingly follow the N iterations of a loop,  èit will place the cursor appropriately, and� then build on T or SPACE:  èthe loop will be well executed, but in fast mode. Limitations: ############  - The bit 3 & 5 of the register F are not reproduced correctly.  - Interruptions are not emulated. Source/Memory visualization ########################### Orgams try to find source line� matching� the opcode under cursor '>'.  èIt can fail, rightly or� wrongly,� thus displaying "source not found".  èThis feature slow down step-by-step trace, mostly in case of failure. Kindly press CONTROL-V switch to memory dump, to last address selected  èvia 'M' command in monitor. This mode doesn't penalize trace's speed. Back to source ############## CONTROL-ESC returns to editor at currently visualized line, contrarily  èto ESC-ESC which leaves editor cursor untouched. Back to the program. #################### Return by pressing J (like 'J'UMP). The� state of the Z80 is restored:  èthe point of view of registers it� is� as if we had called the routine  è''PUSH AF: POP AF: RET''. Of course� if� the program was not traced by  èstep was taken with the current valu es of registers. The CRTC registers are restored with the system defaults.   with the current values of registers. The CRTC registers are restored with the system defaults.