# Introduction There are two main versions: * the online IDE [ASM80.com](https://www.asm80.com) * [Node.js command line utility](https://www.npmjs.com/package/asm80) Here are described both of them. # Source Code Line can begin with a label. Label should be followed by ":", but colon can be omitted. Everything after a ; in a line is a comment (unless the ; is part of a string literal, of course). There are no multiline comments. String literals are written to the object file without any character set translation. In case you use punctuated character, the lower byte of its Unicode representation will be used. Blanks are significative only in string literals and when they separate lexical elements. Any number of blanks has the same meaning as one. A blank between operators and operands is allowed but no required except when the same character has other meaning as prefix ('$' and '%', for example). ## Numeric literals Numeric literals can be written in decimal, binary, octal and hexadecimal formats. Several formats are accepted to obtain compatibility with the source format of several assemblers. * A literal that begins with $ is a hexadecimal constant, except if the literal is only the $ symbol. * A literal that begins with a decimal digit can be a decimal, binary, octal or hexadecimal. If the digit is 0 and the following character is an X, the number is hexadecimal. If not, the suffix of the literal is examined: D means decimal, B binary, H hexadecimal and O or Q octal, in any other case, is taken as a decimal. Take care, `FFFFh`, for example, is not a hexadecimal constant, is an identifier, to write it with the suffix notation you must do it as `0FFFFh`. ### Floating point numbers (v2.5.3+) Only the decimal numbers can be float. You can use only the decimal point syntax, not the "E" syntax. Use .pragma directive to specify what to do with the float number. ## String literals There is one format of string literals. They should be double quote delimited. *Assembler can parse single quote form too, but it should produce an error, when delimitation is used in string, so please use double quotes.* A string literal of length 1 can be used as a numeric constant with the numeric value of the character contained. This allows expressions such as `'A' + 80h` to be evaluated as expected. ## Identifiers Identifiers are the names used for labels, EQU symbols and macro names and parameters. The names of the CPU mnemonics, registers, and flag names, and of assembling directives are reserved and can not be used as names of identifiers. Reserved names are case insensitive, even if case sensitive mode is used. Identifiers are not case sensitive. Internally are converted to uppercase. ## Expressions Parser can evaluate simple math expressions, with all of the common operators, like +, -, /, \*, # (modulo). You can use identifiers as a variables too, e.g. `LOOP + 3`. There are some specials here, like string repetitions (`"A"\*3` produces `"AAA"`) or upper / lower part of identifier value. If LOOP is 0x1234, then \LOOP means 0x12 ## Math operators | Operator | Meaning | | ----------------------- | ------------------------------------------------------------------- | | +, - | Arithmetic add, subtract | | \*, / | Arithmetic multiply, divide | | #, % | Arithmetic modulo (the remainer of division) - equivalent operators | | ^ | Power (2^5 = 32) | | , | Append operands | | &, \| | Binary and, or | | \|\| | String concatenation | | =, !=, ?>, ?<, ?>=, ?<= | Relative operators | ## Functions | Function | Meaning | | --------- | ------------------------------------------- | | isnear(x) | 1 if x is in range \[-128;127], 0 otherwise | | lsb(x) | Least significant byte | | msb(x) | Most significant byte | ``` .macro jeq .if isnear(%%1-$) beq %%1 .else bne $+5 jmp %%1 .endif .endm ``` ## Listing For each compiled file the listing (.lst) is generated. You can see all lines with their addresses and opcodes. At the bottom is all variables dump as well as cross-reference (where is given variable defined and where is used) # Machines Right CPU is determined by file name extension, or by [.engine directive](/directives). Supported file name extensions are: * Intel 8080: .A80 * Intel 8008: .A08 * Zilog Z80: .Z80 * Motorola 6800: .A68 * Motorola 6809 / Hitachi HD6309: .A09 * MOS 6502: .A65 * WDC 65816: .816 * CDP 1802: .A18 # Directives | Directive | Meanings | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Output controls** | | .cpu | Select CPU type. Available values are: 8080, 8008, Z80, 6502, M6800, CDP1802, M6809, C65816 | | .engine | Controls machine type for emulation (only in online [ASM80](https://www.asm80.com/)). Available values are: PMI, PMD, JPR, KIM, SBCZ80, SBC6502, SBC09, ZXS and CPM | | .pragma srec | Makes S19 file in addition to the HEX | | .pragma sna | Makes SNA file instead of HEX (only for Z80) | | .pragma tap | Makes TAP file instead of HEX (only for Z80) | | .pragma prg | Makes C64's PRG file instead of HEX (only for 6502) \[[read more](https://www.uelectronics.info/2015/04/10/asm80-news-cpm-c64-etc/)] .PRAGMA PRG ;says “make .PRG instead of .HEX” .ORG $0810 ;or higher .ENT $ ;for “enter here” | | .pragma com | Makes CP/M COM file instead of HEX (only for Z80/8080) \[[read more](https://www.uelectronics.info/2015/04/10/asm80-news-cpm-c64-etc/)] | | .pragma html | Makes HTML listing (instead of LST) | | .pragma segment | Make separate HEX files for cseg, dseg and eseg (without this pragma are all of them in one HEX) | | .pragma hexlen,X | Make HEX records X bytes long (e.g. *.pragma hexlen,8* will make very short HEX line). Usable when some software needs exact length of a HEX record. | | .pragma nofloat | All float numbers are stripped down to the integer (just drop all the digits after the decimal point) | | .pragma float | Leave FP numbers intact | | .pragma roundfloat | All FP numbers are rounded to their nearest integer | | .binfrom *addr* | Starting address for binary download, default is 0. *(Only valid for "Download BIN" function in IDE)* | | .binto *addr* | Last address for binary download (this address WILL NOT BE INCLUDED in binary file) Default is 65536. *(Only valid for "Download BIN" function in IDE)* | | .error *message* | Throws an error during compile phase. | | | **Data definition** | | db (aliases: defb, fcb) | Define Byte. The argument is a comma separated list of string literals or numeric expressions. The string literals are inserted in the object code, and the result of the numeric expression is inserted as a single byte, truncating it if needed. You can use DUP for entering N same values: DB 10 DUP (123) means "10 times value 123" | | dw (aliases: defw, fdb) | Define Word. The argument is a comma separated list of numeric expressions. Each numeric expression is evaluated as a two byte word and the result inserted in the proper "endianity". You can use DUP for entering N same values: DW 10 DUP (123) means "10 times value 123" | | dd | Define Double Word. The argument is a comma separated list of numeric expressions. Each numeric expression is evaluated as a four bytes and the result inserted in the proper "endianity". | | df | Define Float number. The argument is a comma separated list of numeric expressions. Each numeric expression is evaluated as an IEEE-754 32bit floating point number and the result inserted in the proper "endianity". | | dff | Define double precision Float number. The argument is a comma separated list of numeric expressions. Each numeric expression is evaluated as an IEEE-754 64bit floating point number and the result inserted in the proper "endianity". | | ds (aliases: defm, defs, rmb) | Define Space. Take one argument, which is the amount of space to define, in bytes. | | fill *value, length* | Fill memory with a value. Take two arguments, the first is a value, the second is length of filled block (byte count). | | bsz *length*(alias: zmb) | Fill memory with a given count of zeros. | | .cstr | When you need write a zero-ended string (C style), you can use `DB "Hello",0` - or simple `.cstr "Hello"` | | .pstr | Similar as .cstr, but there is no trailing zero. .pstr is a Pascal-style string: first byte is length, then string. So `.pstr "Hello"` is equal to `DB 5, "Hello"`. | | .istr | Strings are often defined as simple ASCII, where the last byte has bit 7 set to 1. So `.istr "Hello"` is the same as `DB "Hell","o"+0x80` | | .include *filename* | Include a file. The file is readed and the result is the same as if the file were copied in the current file instead of the INCLUDE line. The file included may contain INCLUDE directives, and so on. INCLUDE directives are processed before the assembly phases, so the use of IF directives to conditionally include different files is not allowed. | | .include *filename:block* |

Include a part of a file, or better say: the block with given name from a file. The file is searched for the .block name ... .endblock sequence. and the result is the same as if the block were copied in the current file instead of the INCLUDE line.
You can use the placeholder "this" as a file name. In that case parser will use the same file for looking, e.g. .include this:common includes the "common" block from the same file.

| | .incbin *filename* | Include a binary file. No parsing, no compiling, just a bunch of DBs. | | | **Code control** | | org *addr* | ORiGin. Establishes the origin position where to place generated code. Several ORG directives can be used in the same program, but if the result is that code generated overwrites previous, the result is undefined. | | .ent *addr* | ENTer point for debugging. I.e. **.ent $** | | .align *N* | The .align directive causes the next data generated to be aligned modulo N bytes. | | .phase *addr* | Continue to produce code and data for loading at the current address but assemble instructions and define labels as if they originated at the given address. Useful when producing code that will be copied to a different location before being executed. | | .dephase | End phase block. | | | **Preprocessor** | | equ (alias: =) | EQUate. Must be preceded by a label. The argument must be a numeric expression, the result is assigned to the label. I.e. **VIDRAM equ $4000** | | .set | Variable equate. Must be preceded by a label. The argument must be a numeric expression, the result is assigned to the label. **The main difference between .set and equ is that the EQU cannot be redefined, but .SET can be overwrited later in the source code** | | | **Conditional blocks** | | .if *cond* | Contional assembly. The argument must be a numeric expression, a result of 0 is considered as false, any other as true. If the argument is true the following code is assembled until the end of the IF section is encountered, else is ignored. The IF section is ended with a ENDIF directive. IFs can be nested (from version 2.5.2). | | .ifn *cond* | IF NOT | | .else | The IF branch, valid for false condition. | | .endif | End of the IF block | | | **Macros and blocks** | | .macro *macro\_name* | Defines a macro, see [the chapter about macros](/macros). | | .rept *count* | Repeat a block of code substituing arguments. See [the chapter about macros](/macros). | | .endm | End of MACRO definition or REPT cycle. | | .block | Start of logical block. All labels, defined in this block, are local. It means you can’t reference them from outside the block. If you want to define a label globally, simply prefix it with ‘@’, like @LABEL: Good idea is to enclose INCLUDEd code into block. Block can have its own name, e.g. *.block serial* It is usable with *.include* directive to include only specific block from a file. Just use *.include library.a80:serial* - syntax is *file:block* - with a colon as a separator. | | .endblock | End of BLOCK. | | | **Segments** | | | *Segments has its own independent ORG pointers, so you can e.g. defined, that data segment begins at 8000h. You can mix data and code together as you need, but assembler keeps code in one chunk, data in another etc.* | | .cseg | Following code is a program (code segment - default) | | .dseg | Following source code is a data (data segment) | | .eseg | Following source code belongs to third segment (extended) | | .bsseg | Following source code is a not-initialized segment. ASM allows only DS and such directives, which does not generate any content | | | **6809 directives** | | setdp | Allows the user to set which memory page the assembler will use for the direct page addressing mode. if "SETDP $D0" is encountered, the assembler will then use direct addressing for any address in the range of $D000 to $D0FF. *This directive does not actually affect the contents of the direct page register.* | | .pragma 6309 | Enables HD6309 added instructions in the 6809 assembler sources | | | **65816 directives** | | .m8 | Accumulator is 8bit | | .m16 | 16bit accumulator | | .x8 | index register is 8bit | | .x16 | 16bit index | # Macros Define macro with .macro and .endm. You can use a parametric macros - any parameter is addressable by %%1, %%2, %%3, ... For example, such code: ``` .macro decadd adi %%1 daa .endm ; Use this macro decadd $22 ``` will generate this: ``` 0000 ; Use this macro **MACRO UNROLL - DECADD 0000 87 22 ADI $22 0001 27 DAA ``` ## Local labels Macros has no local label mechanism. So if you define a label in a macro, it unrolls to the same label, ending with a "redefine label" error message. There is a workaround to define unique label for each macro unrolling: ``` .macro xyz loop%%M: inc a dec b jr nz,loop%%M .endm ``` Now it is safe to use this macro repeatedly, because special placeholder "%%M" is replaced by string "M\_"+line number. It provides a good enough workaround for local labels. ## Compound parameters Let's imagine a macro: ``` .macro test db %%1 dw %%2 .endm ``` If you use this macro in such form, everything is OK: ``` test $12, $3456 ``` Two parameters is OK. But what if you need the first DB is something like `db $de,$ad,$be,$ef`? You can use the compound parameter: ``` test {$de,$ad,$be,$ef}, $3456 ``` ## Rich syntax (v2.5.2+) A macro can be defined by standard syntax as `.macro name`, or more consistent way as `name: .macro` or `name .macro`. ## Formal parameters (v2.5.2+) Now you can name formal parameters too. For example - assume a macro cpymem for copy memory content. Such macro has three arguments - source, destination and length. The old form of macro has *mute parameters*, just referenced by its number: ``` .macro cpymem LD HL,%%1 LD DE,%%2 LD BC,%%3 LDIR .endm ``` New formal parameters, introduced in revision 2.5.2, allows to write this: ``` .macro cpymem, src, dst, len LD HL,src LD DE,dst LD BC,len LDIR .endm ``` Preprocessor also check if the number of given parameters is sufficient for the macro, i.e. you cannot specify less parameters than formal, like `cpymem 100, 200`. All those named parameters are strictly local (in fact, they are replaced with its values before assembly phase). # Procesor-specific syntax ## 6502 * **Zero page** Assembler tries to determine if zero page mode is suitable. It needs the operand value is computable in the first pass (so no forward reference, no intensive math etc.) If you need implicitly select zero page mode, simply prepend asterisk (\*) sign before the operand. ## 6809 * **Direct, or extended?** Assembler tries to determine which mode is suitable. It needs the operand value is computable in the first pass (so no forward reference, no intensive math etc.) If you need implicitly select one mode, use signs < (for direct) or > (for extended) right before the operand. ## 6800 * **LDA A or LDAA?** Use literally what you want to use. Compiler internally transfer all of these instructions into long syntax (without a space), so LDA A becomes LDAA etc. ## 8008 * **LAB or MOV A,B?** ASM80 supports both syntax flavors for Intel 8008, the older one (with mnemonics like LAB, LDA, LAD, CAL etc.) as well as the newer one, compatible with 8080 (MOV A,B, MVI etc.) * **CPE, SBC etc. ambiguity** ASM80 performs an intelligent decision between old and new syntax. Unfortunately, some instruction in old syntax (like CPE - compare A and E) has a new meaning in new syntax (CPE is Call When Parity Even). ASM80 can decide on the base of parameters. "CPE" without parameters is "old Compare", "CPE $0123" is "new CALL". # Generic Emulators Barebone emulator, or “generic emulator”, is a customizable emulator of CPU + memory + serial terminal. You can configure it by simple config file. Let’s long story short… First of all, prepare a config file, e.g. “mycomputer.emu”. Extension “.emu” is mandatory. File should contain this: ``` cpu Z80 memory.ram.from 0x1000 memory.ram.to 0x13ff memory.rom.from 0x0000 memory.rom.to 0x0fff ;serial simple ;serial.in 1 ;serial.out 1 ;serial.status 0 ;serial.status.available 0x20 ;serial.status.ready 0x02 serial 6850 serial.data 0x81 serial.control 0x80 terminal.caps 1 ``` Format is really simple: Each line contains one directive. Lines with “;” at the same beginning are comments. Here are parameters: | parameter | value (case sensitive) | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cpu | can be “I8080”, “Z80” or “C6502” | | memory.ram.from | starting address for RAM (please follow the 0x… convention for hexadecimal numbers) | | memory.ram.to | last address of RAM | | memory.rom.from, memory.rom.to | Same as above, but for ROM (your source code should lays here) | | serial | Type of serial port. You can select “6850” or “simple”. See below | | serial.data, serial.control | For 6850 serial – two ports. | | serial.in, serial.out | in and out ports for “simple serial port” | | serial.status | “Simple port” status. Read only port. It returns “serial.status.available” when there is any data for read, and “serial.status.ready” if port is ready to send a data. | | terminal.caps | 1 sets terminal to caps lock (default value 0 means “no caps”) | | serial.interrupt | value 1 means that terminal invoke CPU interrupt on keypress (=serial data is ready for read). Default 0 means “no interrupt”. | Two serial ports are available – 6850 is the standard ACIA circuit, “simple” is a generic serial port with no complicated functions, just read and send bytes. How to use it? It’s simple, just tell which emulator should use by the “.engine” directive (without “.emu”), like this: ``` org 0 .engine mycomputer di ld sp, 0x1400 ld a, 15h out (80h),a ld hl, hello call printhl endless: call geta jr z,endless inc a call printa jr endless printhl: ld a,(hl) or a ret z call printa inc hl jr printhl printa: push af serdy: in a,80h and 02 jr z,serdy pop af out 81h,a ret geta: in a,80h and 01h ret z in a,81h or a ret hello: db "Hello World!",0x0d,0x0a,0 ``` It’s a simple “hello” program, using the above configuration. Just save it as “test.z80” and click to “Emulate (F10)”. It should compile and run emulator with given configuration. For 6502-based computer you can use this config file (e.g.”my6502.emu”): ``` cpu C6502 memory.ram.from 0x0000 memory.ram.to 0x0fff memory.rom.from 0xf000 memory.rom.to 0xffff serial 6850 serial.data 0xa001 serial.control 0xa000 serial.map 1 ``` Please notice the “serial.map” directive. It means that serial port is not mapped into “I/O” space (like Z80/8080 does), but into memory space. Serial.data and serial.control are addresses now. 6502 requires RAM in a bottom part of address space, ROM at the top. Try this code: ``` .engine my6502 ACIA = $A000 ACIACONTROL = ACIA+0 ACIASTATUS = ACIA+0 ACIADATA = ACIA+1 .ORG $FFFC DW reset DW reset .org $f000 RESET: LDX #$FF TXS LDA #$15 STA ACIAControl LDY #0 LOOP: LDA Message,Y BEQ KEY JSR SEROUT INY BNE LOOP KEY: LDA ACIAStatus AND #1 BEQ KEY LDA ACIAData ; simple data mangling SEC ADC #0 JSR serout JMP KEY Message: DB $0C,"My hovercraft is full of eels!",$0D,$0A,$00 SEROUT: PHA SO_WAIT: LDA ACIAStatus AND #2 BEQ SO_WAIT PLA STA ACIAData RTS ``` Other processors and peripherals are on its way… # IDE stuff # IDE: Workspaces Workspaces allows you to organize your source codes into separated "projects". A workspace is a space which contains all your files, as you see in left column (file selector). Your primary workspace is saved in your browser. It means all your files are gone when your browser is reinstalled, or you sit behind another computer. To avoid file loss, downloading workspace is recommended. Better way is to use an online workspaces. When you establish an user account, you got a space for your workspaces in the ASM80 cloud storage. Don't worry, they're still private. ## User account Select "Workspaces online" and log in with your favorite social account. You can use GitHub, Google, Twitter or Facebook. *ASM80 does not required any "write" or "system" privilegies, just "log in".* When you log in for the very first time, an user account for you is created. You can link another service account to your primary log in, so you can log in e.g. with your Google account as well as your GitHub account. ## Workspaces online When you are logged in, you can save all your files from your browser to the cloud storage by clicking on "Save workspace as". You can see the list of your workspaces online too. Click on the remote workspace name does "workspace switch" - active files are saved to cloud workspace, your browser filesystem are cleaned and remote workspace is opened. # IDE: GitHub integration First of all, please log in to your account, as described in [workspaces](/ide-stuff/workspaces). You can import files from GitHub public repository or public gist just by clicking on "Import from GitHub" at the bottom side of the workspace list (left column). You can save all your files in active workspace as a gist. You have to switch to "Workspaces online" and provide your credentials for GitHub. Then you can use the feature "Save workspace as gist". ## GitHub Credentials You will need two information: your user name for GitHub and your personal access token, which you have to [generate here](https://github.com/settings/tokens). Please grant access to gists and repositories when creating token. Your credentials are stored in your online account, so you have to provide it only once. *GitHub token can be revoked, so don't worry...* # Misc stuff # How to generate a C64 .prg You can generate .PRG files for C64 emulators directly, just use these directives: ``` .PRAGMA PRG – says “make .PRG instead of .HEX” .ORG $0810 – or higher .ENT $ – for “enter here” ``` Here is a short video tutorial (use fullscreen and HD for best quality). [![Here is a short video tutorial (use fullscreen and HD for best quality).](https://img.youtube.com/vi/LwnarnR5Z-4/0.jpg)](https://www.youtube.com/watch?v=LwnarnR5Z-4)