VTPT ALASM

From MSX MUSIC WIKI
Jump to: navigation, search

1. MEMORY ALASM can work with a number of source texts at the same time. Each text lies in its own memory page. You can select one text or another to edit using PAGE [page] or ssENTER (from the list). Pages are enumerated as in upper memory driver, using its memory mask. Lower 3 bits of page number are always the same as bits 0-2 of port #7FFD. When ALASM is loaded it tests memory by all 8 bits of page number. It results in screen as XXXX kB mask XX that means ALASM founded XXXX kB of memory and bits in XX are working for changing page. These bits are used to mask pages in PAGE etc. Stack address must not exceed #6dff! ALASM resides in #8000-#bfff. When you compile to #8000-#bfff it is compiled to system page. When you run your program or quit ALASM or use the debugger, #8000-#bfff is switched with system page, so your program sets in its place. ALASM uses lower memory for IMPORT, EXPORT, and MOVE. Compilation uses stack extensively.

2. ALASM COMMANDS

Commands can be interrupted by pressing BREAK. If a command can lose a changed text, it will ask for its saving.

Quit [address][,page]

Quits ALASM. If no parameters given, then exits through RET, else JP to "address" in "page".

Debug

Jumps to STS7.0. (#db06, page given in setup)

Run [address][,page]

Runs the program. By default the "address"=last ORG address, "page"=0.

Work [drv:][filename[.ext]]

Loads the file into current page. Extension is "H" by default. "filename" can contain wildcards (see Catalogue). In this case the last file fitting will be loaded. If "filename" is not given, the user will select the file from list.

Catalogue [drv:][mask]

Shows disk catalogue. By default, mask="*.*" (all files). Mask format: "?" may mean any symbol, "*" means that all the next symbols may be of any kind. Delimiter ("." or end of line) suggests that all the further symbols are spaces. "CATALOGUE C" is a mean to show disk parameters not showing files.

Name [newfilename[.ext]]

Changes the name of the current source text.

Edit [drv:][filename]

Edits text in current page. If filename is given, then file with this name is loaded into the current page. If it is absent on the disk, it is created in memory.

merGe [drv:]<filename>

Adds given source text to the end of current source text.

counT <expression>

Evaluates the arithmetical expression.

sYmbol [mask|=number_expression]

Shows list of labels by mask or by value. Works only after assembly. <number> - label value NoDef - label was not assigned but was used Macro - label is a macro name Wrong - label is undefined due to compilation errors.

Assemble

Assembles (compiles) current source text.

Save [+|!][drv:]

Saves current source text to disk. If "+" is added then all the changed texts will be saved. If "!" then all the texts in the memory will be saved.

Move

Executes TR-DOS MOVE. Uses memory lower than #7400.

Info

Shows version number, list of system pages, and list of files (texts) in the memory. Changed texts are marked with '+'. Files with compilation errors have error count, others have first line shown.

Page [page]

The page given becomes current.

driVe <drv>

The drive given becomes current.

Jumb [+]

If no parameter it scans the current text to change directives "-" to "+" (this operation is also executed in every source text loading). If "+" is added then scans all the texts in the memory.

ssENTER

Also named ALTER. Allows to select file in memory by means of cursor keys.

Ban [+]

Removes current text (or all the texts in the memory if "+").

The following commands use overlay:

conFig

Setup. Can be saved into ALASM body on the disk.

impOrt [drv:][mask]

Converts plain text files into ALASM format. Mask is filename mask to select a file from. Asks for uppercasing of lowercase token words (leaves them untokenized if no). Asks for line breaking by ":", as ALASM allows only one command per line. If text exceeds page then also asks for next page number.

eXport [+][drv:]

Converts current source (or all if "+") to plain text and saves to disk. Plain text is CR, not CR+LF.

3. EDITOR COMMANDS

Editor has most of screen for editing and lower line for status where current page and filename are shown, and also free space in this page and the size of marked/deleted lines buffer (pocket), as well as text size and edit mode (Ins/Ovr).

Editor commands list (Extend key that is Caps Shift+Symbol Shift):

Quit - quit to main ALASM shell.
Assemble, counT - as in main ALASM shell.
Begin, End - go to begin and end of text.
Search [searchstring]

Searches from position directly after cursor and until the end of text. Search can be repeated by ssI, which will start from current position or from the beginning if cursor is at the end. If searchstring is not given then old searchstring will be used.

sYmbol [labelname]

Searches for label defined (that is in the very beginning of line). labelname can contain few first symbols of the label - all labels starting with this will be found.

Xreplace string1<press Enter>string2

Finds and replaces string1 to string2. Asks for replace: Y - yes, N - no and find further, G - yes and yes further, BREAK - stop.

coDe XXX>[symbol_code]

Inserts symbol with code given. XXX shows symbol code under cursor.

Restore

Inserts pocket data (marked and deleted lines) after cursor. Resets pocket add flag, so the next pocket operation will clear the pocket.

Clear

Clears pocket.

Ins/ovr

Changes edit mode: insert to overwrite or back. State can be saved via config.

Undo

Undoes changes in current line (if cursor was not yet moved from it). Revertible by means of itself.

Labels

Shows all labels having no further text in their lines. They are generally procedure names. User can navigate between them with cursor keys and Enter, or can BREAK.

Edit mode keys: ssI - continue search ssQ (Home on PC keyboard) - moves cursor to the 0th column ssE (End on PC keyboard) - moves cursor to the end of line ssSpace - delete current line. It is added to the pocket ssW (Ins on PC keyboard) - "marks" line that means it is added to the pocket

If the pocket adding flag is off (after Restore) the pocket is emptied before the operation

csSP - tabulation or Rus/Lat (can be switched in config) cs1 - Rus/Lat or tabulation cs2 - inserts space under cursor (always insert, never overwrite) ssENTER - the same ALTER as in main ALASM shell cs8 (right arrow) - remembers symbols of previous command

Insert mode:

Symbol is entered moving the rest of the word right.

Word is a part of line having no more that one space in a row. For example, if you enter a label in a line containing mnemonic, the latter will not move.

Left arrow - cursor moves to first nonspace to the left.
Right arrow - cursor moves to first nonspace to the right or the

next tabulation position if no symbols further. All modes:

…nter breaks line apart. If no symbols to the right,

then Enter will go to 8th position where mnemonics are usually entered. If there are symbols to the right and the cursor is in 8th position then tabulation is kept after Enter. This is to move labels from commands.

cs9 (Del on PC keyboard) deletes symbol under cursor. If no symbols further then

joins the next line (in case if the result is no more than 64 symbols)

cs0 (BackSpace on PC keyboard) if pressed at the beginning of the line -

joins it to the previous one.

4. ASSEMBLER DIRECTIVES
       ORG address[,page]

Sets compilation address (regarding DISP shift). By default page is page mentioned in another ORG before. In the beginning of assembly it is 0.

label EQU value Defines label as value. Value may be an expression which is evaluated. See label=value to re-define existing label.

       DISP address

Sets program work address which may be not the same as that where it is compiled.

       ENT 

Sets program work address to current compilation address. Example: SCREEN EQU #4000

       ORG #8000
       LD HL,BEGIN             ;Source: routine
       LD DE,SCREEN            ;Destination: screen area
       LD BC,END-BEGIN         ;Size: routine size
       LDIR                    ;copy
       CALL SCREEN             ;call it
       DI 
       HALT                    ;hang forever

BEGIN DISP SCREEN MARKA DEC A

       HALT 
       JP NZ,MARKA             ;we use JP and it works
       RET 
      ENT 

END

You can get current DISP shift (shift=org-disp) this way: a ORG 0

       ENT 

shift ORG a+shift

       DISP a
       INCLUDE "drv:filename"[,page]

Compiles another source by the way. "filename" is its name on the disk. The name may contain wildcards, and the last fitting file on the disk will load. "" is any file. If it is already in the "page" under this name then it will not load. If "page" is not given then it will load into the current page, overwriting the current source, so it will re-load after included source finishes. The current source will continue from the next line. Example:

       LDIR 
       INCLUDE "TOKENIZE",1
       OTDR 
       INCLUDE "ALASM2"
       HALT 

LDIR will be assembled, then some "TOKENIZE.H" source which will be loaded into page 1, then OTDR, then some "ALASM2.H" source which will be loaded atop of current source, then the current source will re-load from the disk (don't forget to save it before) and continue from HALT.

       MAIN "filename"[,page]

Compiles given main source instead of current one (which is considered a minor unit in the project). Must be the first command in the source. Symbols "." and "*" in the filename must be given as "?". Example:

       MAIN "MAKE6?7",6
       LDIR 

When ASSEMBLE is executed the compilation will start from MAKE6*7 source residing in page 6, which is supposed to INCLUDE this minor unit containing MAIN and LDIR. When INCLUDEd the MAIN directive will be ignored, and the compilation will continue from LDIR.

       INCBIN "drv:filename"[,size]

Includes into compiled code a code block of size bytes (or with size specified in the directory) loaded from disk. If the file on disk is longer than size it will be loaded partially.

       DUP <number>

Beginning of block which is repeated number of times during compilation. Number may be expression as always.

       EDUP 

The end of this block. DUP may be inside another DUP. Example:

       DUP 32
       LDI 
       LD A,B
       OR C
       JR Z,$+3
       LD (HL),D
       EDUP 

This block will compile 32 times. Can use counters made of labels (see label=value) and have conditional compilation branches.

       REPEAT 
       <body>
       UNTIL0 <expression>

Repeats <body> until <expression> will be 0.

       DB byte|string[,byte|string...]

The same as DEFB. Bytes may be expressions (lower byte of the result is used). Example:

       DB "A",13,10,"big",13,5+5,"brown",13,10,"fox",13,10
       DEFB "jumps over",13,10,"the lazy dog",EOFsymbol
       DW word[,word...]

The same as DEFW. Example:

       DW ALASKA,BUFFER,12,#BD15,32767,.NUMB1
       DEFW 12345,34567
       DS howmanytimes[,bytes]

The same as DEFS. Bytes (by default the zero byte) are inserted into the current compilation address so many times as specified. Example:

       DS 10,#E5
       DEFS 32,#ED,#B0
       DD [#]hexbyte[hexbytes]

Compiles hexadecimal bytes.

       DD 1D4FDC,4223

is the same as

       DB #1D,#4F,#DC,#42,#23
       +<something>

DON'T USE WITH LINE SIZE=#2C..#2F! After a text is loaded from disk it is scanned for "+" in the beginning of lines ("-" becomes "+"). Compilation will compile these lines and change "+" to "-" so they will not compile the second time. Example:

       LD HL,#DB00
        +SAVEADR
        +  ORG #DB00,7

+ INCBIN "sts70r" + ORG SAVEADR

       JP (HL)

STS will load only at the first assembly.

label=expression Define or re-define the label. Example: SHLUSS=0

       ORG 32768
       DUP #4000
       DEFW SHLUSS

SHLUSS=SHLUSS+1

       EDUP 

Memory after #8000 will be filled with words 0..16384.

       IF0 <expression>
       <body1>
       [ELSE 
       <body2>]
       ENDIF 

If <expression>=0, the <body1> is compiled, else <body2>.

       IFN <expression>
       <body2>
       [ELSE 
       <body1>]
       ENDIF 

The opposite. Conditional compilation inside conditional compilation is possible, up to 254 layers.

       LOCAL 
       <body>
       ENDL 

Local label block. All labels inside this construction will be invisible outside (except for labels starting from @ which are global labels). LOCAL inside LOCAL is allowed. If a label is defined inside LOCAL block but this label was accessed outside, it will be global:

       LD HL,LABEL
       LOCAL 

LABEL

       ENDL 
       MACRO <macro_name>
       <body>
       ENDM 

Macro definition. Inside macro: \0..\9 - parameter 0,1,2,..9 \C - current symbol in parameters \N - go to next symbol in parameters (returns nothing) \S<char> - string from current symbol until <char> symbol \P - shift parameter numeration. parameter 1 becomes 0 etc. Parameter 0 is returned. \R - restores initial parameters enumeration as it was before \P.

       <macro_name> [parameter1[,parameter...]]

Use macro. Parameters are divided by commas (not counting commas in quotes).

       MACRO DOWN
       LOCAL 
       INC \C
       LD A,\C
       AND 7
       JR NZ,LABEL
       LD A,\N\C
       SUB #E0
       LD \C,A
       SBC A,A
       AND -8
       ADD A,\R\C
       LD \C,A

LABEL

       ENDL 
       ENDM 

This is generic DOWN HL or DOWN DE routine that counts screen address a line lower that current one. Using conditions of this type:

       IF0 "  "-"\1  "

or:

       IF0 ?macroname\1-2

we can use macros with floating number of parameters (see \P to shift them).

       DISPLAY [/L,]["any text",][[/D|/H|/A,][/T,]expression]

Displays messages and/or numbers while assembly. /D, /H, and /A keys define output format for one next number. Numbers without keys are shown in current system (see config). /D - decimal number, /H - hexadecimal, /A - both systems. /L defines displaying in old line, without line leed and carriage return. /T shows the expression given, then its value. Examples:

       DISPLAY "code size: ",/D,end-start
       DISPLAY /A,"abc+xyz=",abc+xyz
       DISPLAY "simple"," text"
       DISPLAY "This is one "
       DISPLAY /L,"message"
       DISPLAY /A,/T,abc+xyz

is the same as

       DISPLAY /A,"abc+xyz",abc+xyz
       RUN address[,page]

Calls the specified routine while assembly. All the Post-labels are not evaluated yet, ALASM is in #8000.

IX and IY halves: HX,HY,LX,LY. This is also possible: INF SLI OUT (C),0 EXA EXD JZ JNZ JC JNC LD L,0,H,'fnt

5. Expressions

Evaluated left to right without priorities (except for brackets). 16-bit signed/unsigned integers are used. a+b a-b a*b a/b a&b - AND a|b - OR a!b - XOR a>b - cyclic shift of word "a" "b" bits right a4+{$}}-#BF43 make  ;mkace!

       ENDIF 
6. ERRORS

0 syntax error 3 JR out of range 6 double definition of a label 10 compilation into ROM 11 wrong operation 12 wrong MACRO operation 14 system stack error 15 disk error Errors after assembly: wrong short - wrong short displacement not defined - label not defined

7. CONFIG
Load FONT codes

Loads font "FONT*" #9c40,#400(#8045,#3f0).

Start page

Page which will be current when ALASM starts.

System page

Where ALASM resides when inactive.

Symbol list

Pages containing labels while assembly and usable after it. If you don't need 4 pages for labels, then zero unused ones from the left. The first page used is the rightmost one. Label pages are filled from their ends.

Post symbols

Pages containing post labels while assembly and unusable after it. Contains data to evaluate labels used prior to define. The first page used is the rightmost one. Post label pages are filled from their starts.

Pocket page

Page containing copy buffer (pocket). Assembly clears it. May be the same as Post.

HImem driver

Sets a driver of higher memory (#7000,#FF)

Files: alasm64 .B - ALASM 64 pitch loader alasm_64.C - ALASM olasm_64.C - overlay FONT64a .C FONT64b .C - font by Faster FIXED

alasm42 .B - ALASM 42 pitch loader alasm_42.C olasm_42.C FONT42a .C FONT42b .C - bold font

sts70r .C - debugger

gruzilka.B - loader from drive B

128ŠDRV .C - 128k memory driver PENTDRV .C - Pentagon 512k memory driver P1MBDRV .C - Pentagon 1M memory driver P4MBDRV .C - Pentagon 4M, or 2M without extra wiring (uses #FD and #AFF7) ATMDRV .C - ATM 1M memory driver PROFDRV .C - PROFI 1M memory driver ZSKAY512.C - SCORP/KAY memory driver (uses 512k on KAY) KAY1DRV .C - KAY 1M memory driver SCORP1M .C - SCORP 1M memory driver

al50stri.H - ALASM format description Fnt42Bld.H - 6x7 (6x6) font converter from screen to #3f0 ALASM font format REFNT42 .H - does the opposite

H_Search.B - searches ALASM sources in ruined disk H_Search.W

Marazm.H, Humor.H, Humor.C Examples of using RANDOM macro that returns pseudo-random number in given range. SNAKE.H The game that plays while ASSEMBLEing it. Credits to RST7 that created this for TASM. BUILD+.H Counts builds of your project and allows to insert this number into your release, as well as edit session number and build date. SAVEOBJ4.H Saves code blocks with any extensions from given addresses with given sizes. Is used with RUN[CS/Enter]. See information inside. No more saving via debugger! SAVEBAS/.H Allows to create a basic file containing your code inside.

INCOMPATIBILITIES WITH v4.44: ORG without page number does not set page 0. Macro parameters are with \, not : DB """,0 now means DB """,0". Write DB 34,0 or DB """",0