Appendix B
Registers, addressing and LWASM
Suppose the debugger says X points at the letter O. LDA ,X+ reads O and advances X. LEAX packet,PCR finds the address of the letter and puts that address in X. The result in the register tells you which question you asked. Keep this page beside the receiver when one printed symbol changes the meaning of a line.
Read the register display
| Look here | Use it for |
|---|---|
| A, B, D | Two 8-bit accumulators or one 16-bit value. A is the high byte of D. A change to A or B changes D immediately. |
| X, Y, U, S | Four 16-bit registers for indexed addressing. U and S can also address stacks. Hardware uses S on a subroutine call or interrupt. |
| PC, DP | Find the next instruction. Supply the upper address byte for a direct-page operand. |
| CC | Read the condition bits from high to low as E, F, H, I, N, Z, V, C. On a compare, read C for unsigned borrow and N together with V for signed order. |
| HD6309 E, F, W, Q | E and F form W, just as A and B form D. Q combines D above W. |
| HD6309 V, MD | V is another 16-bit register. MD controls the processor’s execution mode and FIRQ frame choice and reports trap status. |
The names E, F and V each appear twice in the Hitachi debugger. The accumulators E and F hold eight bits each, and the register V holds sixteen. The flags CC.E, CC.F and CC.V each hold one bit. For an interrupt return the saved CC.E answers whether an entire state frame was stacked. For a 6309 transfer the E register is the high half of the count in W. The interrupt exercise and the block-copy exercise let you see the distinction.
A
MC6809 and HD6309
Eight-bit accumulator. A forms the high byte of D.
Reading: Motorola (1981), ch. 1.
B
MC6809 and HD6309
Eight-bit accumulator. B forms the low byte of D.
Reading: Motorola (1981), ch. 1.
CC.C
MC6809 and HD6309
Carry or borrow. An unsigned addition sets C when the sum exceeds the register. A comparison sets C when the unsigned left operand is lower.
Reading: Motorola (1981), ch. 1.
CC.E
MC6809 and HD6309
Entire state stacked. RTI checks E in the saved condition byte to choose between the short and full interrupt frames.
Reading: Motorola (1981), ch. 1.
CC.F
MC6809 and HD6309
Fast interrupt request mask. Set F to mask FIRQ. A saved CC value can restore the previous mask.
Reading: Motorola (1981), ch. 1.
CC.H
MC6809 and HD6309
Half carry. An eight-bit addition places the carry from bit 3 here. DAA uses H to adjust a packed decimal result.
Reading: Motorola (1981), ch. 1.
CC.I
MC6809 and HD6309
Interrupt request mask. Set I to mask IRQ. Clear I to permit IRQ when the external request is active.
Reading: Motorola (1981), ch. 1.
CC.N
MC6809 and HD6309
Negative. For operations that set N from the result, it copies the most significant bit. A signed comparison also needs V.
Reading: Motorola (1981), ch. 1.
CC.V
MC6809 and HD6309
Signed overflow. For example, adding one to $7F produces $80 in a byte and sets V.
Reading: Motorola (1981), ch. 1.
CC.Z
MC6809 and HD6309
Zero. Many arithmetic and load instructions set Z when the result is zero. After a compare, BEQ uses Z to test equality.
Reading: Motorola (1981), ch. 1.
Condition codes
Other spellings: CC.
MC6809 and HD6309
CC holds eight one-bit values. E marks an entire interrupt frame. F masks FIRQ, H is half carry, I masks IRQ. N is negative, Z zero, V signed overflow and C carry or borrow.
Branch choices depend on how the previous instruction defined these bits. For example, Z=1 after CMP means equal; C=1 after CMP means unsigned lower. An undefined bit cannot support a portable decision.
Reading: Motorola (1981), ch. 1.
D
MC6809 and HD6309
Sixteen-bit accumulator built from A (high) and B (low). Writing D immediately changes both halves.
Reading: Motorola (1981), ch. 1.
DP
MC6809 and HD6309
Direct-page register. Its byte supplies the upper address bits of a direct operand. LWASM SETDP describes your assumption during assembly.
Reading: Motorola (1981), ch. 1.
E
HD6309 only
Eight-bit accumulator and high byte of the HD6309 W register. CC.E is a separate flag.
Reading: Burke (1993), register file.
F
HD6309 only
Eight-bit accumulator and low byte of W. CC.F is the fast-interrupt mask.
Reading: Burke (1993), register file.
HD6309 modes
HD6309 only
The HD6309 starts in emulation mode. Many instructions take fewer cycles in native mode. LDMD #1 selects native mode with the ordinary short FIRQ frame. Mode selection is independent of the LWASM target.
MD bit 0 selects native mode. Bit 1 selects full FIRQ stacking. A native full-state interrupt frame includes E and F; the mode on return must agree with the frame. Cycle counts also depend on indexed postbytes, branch outcomes and transfer lengths. In VCC Plus, Step completes a TFM instruction across its byte transfers.
Reading: Atkinson (2009), pp. 2, 120, 136, 144 · Burke (1993), mode register · VCC Plus, Native Debugger, HD6309 Step.
MD
HD6309 only
Mode register. LDMD controls execution mode and FIRQ stacking. BITMD tests the latched illegal-instruction and division-by-zero status.
Reading: Burke (1993), register file.
PC
MC6809 and HD6309
Program counter. Branches, jumps, calls and returns change the address of the next instruction.
Reading: Motorola (1981), ch. 1.
Q
HD6309 only
Thirty-two-bit accumulator. From most to least significant its bytes are A, B, E, F. D is the high word and W the low word.
Reading: Burke (1993), register file.
S
MC6809 and HD6309
Sixteen-bit hardware stack pointer. JSR, interrupts and PSHS use memory below S. Initialize a writable stack before making a standalone call.
Reading: Motorola (1981), ch. 1.
U
MC6809 and HD6309
Sixteen-bit user stack pointer, also available as an index register. PSHU and PULU use this stack.
Reading: Motorola (1981), ch. 1.
V
HD6309 only
Additional 16-bit HD6309 register used in register operations. CC.V is a separate overflow flag.
Reading: Burke (1993), register file.
W
HD6309 only
Sixteen-bit accumulator combining E (high) and F (low). TFM uses W as a byte count.
Reading: Burke (1993), register file.
X
MC6809 and HD6309
Sixteen-bit index register. Use X to address a table or traverse bytes.
Reading: Motorola (1981), ch. 1.
Y
MC6809 and HD6309
Sixteen-bit index register. X and Y can walk independent buffers.
Reading: Motorola (1981), ch. 1.
Decode an operand
Read the punctuation first. In these LWASM patterns, # selects the value itself; < or > requests a shorter or longer address encoding. An indexed operand describes how to form an address. Brackets add a pointer fetch. The instruction determines what happens to the resulting value or address.
| Look at the receiver’s source | What to check in the debugger |
|---|---|
LEAX packet,PCR |
X receives the assembled address of the packet. PCR lets the assembler encode its distance from the following instruction. |
ADDA ,X followed by LDA ,X+ |
Both instructions read the same byte. Only the second advances X. Follow the saving and restoring of A around the copy. |
JSR [CHROUT] |
The two bytes at the CHROUT vector supply the subroutine address. At entry the saved return address is on S. |
BNE next |
The displacement is signed, measured from PC after the branch operand. This branch goes backward while the count is nonzero. |
A CPU address selects memory through the current map. It identifies a location within a physical RAM block only when that block supplies the access. The MMU lesson shows how to check the active task, block and offset before drawing conclusions from a memory dump.
Direct
MC6809 and HD6309
LDA <$34
Join DP with the 8-bit operand to make the memory address. With DP=$12, LDA <$34 reads $1234.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Extended
MC6809 and HD6309
LDA >$0400
Use the full 16-bit address in the instruction. LDA >$0400 reads a byte there.
On the CoCo 3, the address in STA >$1A00 selects a byte through the CPU memory map. The MMU chooses the physical 8 KiB block and preserves the low 13 address bits. Use Mapped CPU in the debugger to inspect that store.
Reading: Tepolt (1987), p. 20, fig. 3-4 · Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
HD6309 indexed
HD6309 only
LDA E,X · LDA ,W++
E, F and W can supply offsets for X, Y, U or S. W also supports ,W, offset,W, ,W++ and ,--W, including their indirect forms.
Reading: Atkinson (2009), p. 148 · Astle, LWTools 4.25, ch. 3.
Immediate
MC6809 and HD6309
LDA #$20
Use the following operand bytes as the value.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Indexed
MC6809 and HD6309
LDA ,X+ · LDD 2,S · LDA B,Y
Calculate an address from a register and an offset. LDA ,X+ reads at the original X then increments X by one. Use ,X++ for a two-byte advance. Indexed operands can also use A, B or D as signed offsets.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Indirect
MC6809 and HD6309
LDA [,X++] · JMP [$4000]
Use square brackets to fetch a two-byte pointer at the intermediate address, then access the final address. Use a two-byte increment when walking a pointer table.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Inherent
MC6809 and HD6309
INCA
The opcode specifies the operation and its operands. INCA, for example, acts on A.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Relative
MC6809 and HD6309
BNE again · LDA table,PCR
Add a signed displacement to PC after the operand. Branch targets are labels. Indexed PC-relative data references use PCR in LWASM.
Reading: Motorola (1981), ch. 2 · Astle, LWTools 4.25, ch. 3.
Assembler index
When you single-step, the processor fetches instruction bytes. FCC "ORB" produces three data bytes; EQU records a value the assembler can substitute later; END start supplies the execution address for this DECB build. None is a step the processor takes to construct the packet. The linked build shows how a symbol that names a location in one module receives its final CPU address.
Find the directive by its name or its alternative spelling in this book's search. Each entry gives the canonical LWASM syntax. Sections, imports, exports and relocatable object output belong together. Origin and entry directives for an absolute binary belong to a different build. A directive that reserves storage can advance the location counter without depositing a known byte; use an explicit initializer when the exercise depends on that byte’s first value.
*PRAGMAPOP
*PRAGMAPOP
Restore saved pragma settings.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
*PRAGMAPUSH
*PRAGMAPUSH
Save pragma settings on the assembler’s pragma stack.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ALIGN
ALIGN boundary
Advance to a boundary divisible by the supplied value.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
DEPHASE
DEPHASE
Resume the original address calculation after PHASE.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
DTB
DTB
Emit six host-local date and time bytes.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
DTS
DTS
Emit a textual build timestamp. Its value changes with the host clock.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ELSE
ELSE
Select the alternate branch of a conditional assembly block.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
END
Other spellings: .END.
END entry
Finish the assembly and specify the DECB execution address. END itself emits no machine instruction.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ENDC
Other spellings: ENDIF.
ENDC
Close the current conditional assembly block.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ENDM
ENDM
Finish a macro definition.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ENDS
Other spellings: ENDSTRUCT.
ENDS
Close a structure definition.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ENDSECT
Other spellings: ENDSECTION.
ENDSECT
Finish the current object section.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
EQU
Other spellings: =.
name EQU expression
Assign a fixed value to a symbol.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ERROR
ERROR message
Report an assembly error with the supplied text.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
EXPORT
Other spellings: .GLOBL.
EXPORT name
Expose a symbol to other object modules.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
EXTDEP
name EXTDEP
Mark an external symbol as a link dependency without emitting storage for it.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
EXTERN
Other spellings: EXTERNAL, IMPORT.
name EXTERN
Declare a name defined in another object module.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FCB
Other spellings: .BYTE, .DB.
FCB byte[,byte…]
Emit each expression as one byte. The listing shows data at the current location.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FCC
Other spellings: .ASCII, .STR.
FCC /text/
Emit character bytes between matching delimiters.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FCN
Other spellings: FCZ, .ASCIZ, .STRZ.
FCN /text/
Emit a string followed by a zero byte.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FCS
Other spellings: .ASCIS, .STRS.
FCS /text/
Emit a string with the high bit set in its last character.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FDB
Other spellings: .WORD, .DW.
FDB word[,word…]
Emit 16-bit words, high byte first.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FDBS
FDBS word[,word…]
Emit 16-bit values low byte first, opposite to the processor’s normal word order.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FILL
FILL byte,count
Emit the given byte repeatedly.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
FQB
Other spellings: .4BYTE, .QUAD.
FQB value
Emit 32-bit quantities, high byte first.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFDEF
IFDEF symbol
Test whether a symbol has already been defined.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFEQ
IFEQ expression
Include the following block when the expression equals zero.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFGE
IFGE expression
Include the block when the expression is zero or positive.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFGT
IFGT expression
Include the block when the expression is positive.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFLE
IFLE expression
Include the block when the expression is zero or negative.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFLT
IFLT expression
Include the block when the expression is negative.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFNDEF
IFNDEF symbol
Test whether a symbol is still undefined.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFNE
Other spellings: IF.
IFNE expression
Include the block when the expression is nonzero.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFP1
IFP1
Legacy pass-number conditional. LWASM warns that it cannot reproduce pass-one assembly semantics.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFP2
IFP2
Legacy pass-number conditional. LWASM warns that it cannot reproduce pass-two assembly semantics.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFPRAGMA
Other spellings: IFOPT.
IFPRAGMA option
Include a block according to the current pragma setting.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
IFSTR
IFSTR comparison,arguments
Include a block according to the specified string comparison.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
INCLUDE
Other spellings: INCL, LIB, USE.
INCLUDE filename
Read another source file at this location.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
INCLUDEBIN
INCLUDEBIN filename
Copy bytes from a binary file into the assembly output.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
INCLUDESTR
INCLUDESTR string
Treat the contents of the given string as additional assembler source.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
MACRO
Other spellings: MACR.
name MACRO
Begin defining a sequence of source lines for later expansion.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ORG
ORG address
Set the address of the following output. In DECB an origin determines where a data block loads.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
PHASE
PHASE expression
Give following code a different logical address for labels and expressions while retaining its output placement.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
PRAGMA
Other spellings: *PRAGMA, **PRAGMA, OPT.
PRAGMA option
Change a LWASM dialect option. A target-changing pragma affects subsequent assembly.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
REORG
REORG
Restore the location associated with the previous ORG.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
RMB
Other spellings: .BLKB, .DS, .RS.
RMB count
Advance the location counter by a number of bytes. Use ZMB when the load image must contain zeros.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
RMD
Other spellings: RMW.
RMD count
Reserve 16-bit words.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
RMQ
RMQ count
Reserve 32-bit values.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
SECTION
Other spellings: SECT, .AREA.
SECTION name
Begin a section in an object module. The linker determines final placement.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
SET
name SET expression
Assign a symbol a value that later SET statements may change.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
SETDP
SETDP page
Tell the assembler the assumed direct page. Guest software must establish the matching DP value.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
SETSTR
SETSTR name=string
Set an assembler string variable.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
STRUCT
name STRUCT
Begin a structure layout. Field labels describe offsets in its instances.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
WARNING
Other spellings: MSG.
WARNING message
Report a warning with the supplied text.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ZMB
Other spellings: BSZ, FZB.
ZMB count
Emit the requested number of zero bytes.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ZMD
ZMD count
Emit zero-filled words.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
ZMQ
ZMQ count
Emit zero-filled four-byte quantities.
LWASM directive. Its effects take place during assembly.
Reading: Astle, LWTools 4.25, ch. 3.
Dialect, expansion and undocumented spellings
Check the listing before counting debugger steps. A spelling can denote an actual HD6309 operation in one build and a sequence emitted by an assembler pragma in another. The names grouped below describe separate assembler features. The instruction directory identifies the corresponding hardware operations.
ASM-09 dialect
Spellings in this group: IFC, IFNC, EXITM, EXIT.
The ASM-09 compatibility dialect adds string equality and inequality conditionals and an early macro exit.
Reading: Astle, LWTools 4.25, ch. 3.
Assembler conveniences
Spellings in this group: ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE, NEGF, NEGW, NEGQ, TSTQ.
LWASM can expand convenience operations into several instructions when the corresponding pragma is active. The listing gives the actual expansion. A 6809 emulation of CLRD, for example, executes CLRA and CLRB separately.
6809 expansions include ASLD, ASRD, CLRD, COMD, LSLD, LSRD, NEGD and TSTD. These names also identify real HD6309 operations. Additional 6309 convenience spellings include ASRQ, CLRQ, COMQ, LSLE, LSLF, LSLQ, LSRQ, NEGE, NEGF, NEGW, NEGQ and TSTQ. MC6800 compatibility is a separate optional dialect.
Reading: Astle, LWTools 4.25, ch. 3.
Compatibility directives
Spellings in this group: NAM, PAG, PAGE, SPC, TTL, .BANK, .MODULE.
LWASM accepts these listing and tool-compatibility directives without generating code.
Reading: Astle, LWTools 4.25, ch. 3.
MC6800 compatibility
Spellings in this group: ABA, CBA, CLC, CLF, CLI, CLIF, CLV, CPX, DES, DEX, DEY, INS, INX, INY, SBA, SEC, SEF, SEI, SEIF, SEV, TAB, TAP, TBA, TPA, TSX, TXS, WAI.
These optional LWASM spellings expand to 6809 encodings with the 6800compat pragma. Expansion can require several instructions. Inspect the listing when stepping.
Reading: Astle, LWTools 4.25, ch. 3.
OS-9 output directives
Spellings in this group: OS9, MOD, EMOD.
OS9 encodes SWI2 followed by a service byte for OS-9 or object output. MOD and EMOD frame an OS-9 module. Assembly Development runs standalone Disk BASIC block images.
Reading: Astle, LWTools 4.25, ch. 3.
Undocumented and emulator opcodes
Spellings in this group: HCF, RHF, RESET, HALT, BREAK, LOG.
LWASM lists HCF, RHF and RESET for certain 6809 encodings. Behavior outside the documented instruction set can differ by chip. BREAK and LOG are emulator extensions. VCC Plus’s Mac decoder also excludes the optional HALT/BREAK encodings.
Reading: Atkinson (2009), p. 153 · Astle, LWTools 4.25, ch. 3 · VCC Plus, Native Debugger, disassembly.