The SEKA Assembler Guide

By Kenneth Bernholm

This is a guide for the 1984 SEKA assembler by Andelos Systems and Kuma Computers. It's meant as a replacement for the the original SEKA manual.

My reason for writing this guide is not to revive SEKA as a development tool. The Commodore Amiga computer was discontinued in 1996, and SEKA was surpassed by other assemblers long before that. SEKA is a tool that I used for commercial products in the 1980s and now, forty years later, I'm revisiting my past by writing a guide for a dear, old friend.

If you have ever used SEKA and find yourself inspired, I suggest you fire up an Amiga emulator and have a nostalgic afternoon. I enjoyed this project and discovered some SEKA features that I wasn't aware of. Perhaps you will too.


Introduction

This guide covers version 1.4 of the SEKA assembler — an integrated development environment for the Motorola 68000 processor used in the Commodore Amiga and many other computers.

Assembly code, object code, and linked code is stored in memory ensuring a fast edit/assemble/link/debug cycle with no disk access required.

Motorola mnemonics are entered in the editor or loaded from third party text editors and code generators.

The conditional assembler includes macro facilities and produces either absolute or relocatable object code at a rate of 25.000 lines per minute.

Executable code is produced as standard but linkable code can be produced too, resulting in a factor 5-10 speed increase during assembling.

Debugging and code inspection is possible with the symbolic debugger, the line assembler, and the disassembler.

How to Read This Guide

This guide uses special formatting for selected elements:

Regular text
Proper nouns Capitalized and italicised Serif font Proper noun
Proper nouns internal to Motorola 68000 and SEKA Capitalized blue Internal proper noun
Screen, printer, keyboard, and other devices Small caps screen
Input/Output (I/O)
All I/O Monospace font Input/Output
Individual keystrokes and combined shortcuts Black border Keystroke
Terms, commands, flags, instructions, directives, and pointers Uppercase TERM
Parameters, arguments, extensions, expressions, and registers Italic Parameter
Default values Bold Default value
I/O origins
Author (passive information) Gray background information
Reader (literal input for you to type) Orange background input
Computer (literal machine output) Blue background output
I/O delimiters (can be combined)
Optional values Square brackets []
Your values Angle brackets <>
Multiple options separator Pipe |

In a few places, the text is marked in pink. This indicates that I was not able to test the functionality or that it didn't appear to be working.

Assembler Terminology

Descriptions of assembly language often confuses the words "assembly", "assembler", and "assemble". This occurs especially in conjunction with other words, so let's clear it up:

You are an "assembly programmer"; not an "assembler programmer" unless you're writing the assembler tool itself.

You write software in "assembly" or "assembly language"; not in "assembler" which would be like writing software in "compiler".

The Motorola 68000

The Motorola 68000 is a 16/32-bit Complex Instruction Set Computer (CISC) processor. It's named "16/32-bit" because it uses both 16, 24, and 32 bit data sizes.

The Motorola 68000 registers are:

A0-A7 32-bit Address Registers
D0-D7 32-bit Data Registers
SP 32-bit Stack Pointer
SSP 32-bit Supervisor Stack Pointer
USP 32-bit User Stack Pointer
PC 32-bit Program Counter
SR 16-bit Status Register

The A7 and SP registers refers to SSP or USP depending on the s flag in the Status Register.

For further information about the Motorola 68000 processor and how to program it, consult the Motorola 68000 books in The Internet Archive.

SEKA Internals

SEKA always operates in one of these modes:

Every SEKA operation involves one or more memory buffers:

WORK Workspace Buffer
SRC Source Buffer
Clipboard Buffer
CODE Object Code Buffer
DATA Data Buffer
LINK Linker Buffer
RELC Relocation Table for the Object Code Buffer
RELD Relocation Table for the Data Buffer

The start and end of the Source Buffer and the Linker Buffer are represented by pointers:

SOF Start of the Source Buffer
EOF End of the Source Buffer
SOL Start of the Linker Buffer
EOL End of the Linker Buffer

Other pointers:

CLP The Current Line Pointer is the offset line number of the Source Buffer
COP The Current Object Pointer is the memory address immediately following the Code Buffer

Some SEKA commands and assembler directives and some Motorola 68000 mnemonics accepts size extensions for operating exclusively on 8-bit bytes .b, 16-bit words .w, or 32-bit longwords .l. This guide shows size extensions with the default extension in bold: <.b|l|w>.

When SEKA prompts for memory ranges in the form of START> and STOP> addresses, the STOP> address is not included in the memory range. For example, START>$0010 and STOP>$0015 defines the memory from $0010 to $0014. The same rule applies to BEGIN> and END> memory ranges.

Starting SEKA

Type seka to start the SEKA assembler. The program presents you with a copyright message and prompts you for a workspace memory size. 150 kB is a good initial size if the computer is not running other applications:

Andelos 68000 Assembler SEKA v1.5 - Copyright (C) Andelos Systems 1984-1986 Amiga Version -- Sole distributors: Kuma Computers, Pangbourne, Berks, UK WORKSPACE KB>

SEKA is now in Command Mode.

Command Mode

A SEKA> prompt indicates that SEKA is in Command Mode and ready for input.

IMPORTANT Unless otherwise stated, SEKA is case-insensitive like the AmigaDOS filesystem.

Keystrokes and Shortcuts

Command Mode keystrokes and shortcuts:

Return Executes a command and sends the output to the screen
Ctrl+P Executes a command and sends the output to the printer
Ctrl+C Aborts the command you're currently entering
Up Recalls the last command entered

General Commands

Command Mode general commands:

?<e> Evaluate expression Evaluates the expression <e> and shows the result in decimal and hexadecimal
Y Serial mode Enters serial mode where the screen and keyboard communicates on the RS232 serial port. <Ctrl+C>, <Ctrl-S>, and <Ctrl-Q> are interpreted by the connected serial device and not sent to SEKA
RX Read from auxillary Loads data from the RS232 serial port into the prompted BEGIN> and END> memory area
WX Write to auxillary Writes data to the RS232 serial port
! Exits SEKA and returns to AmigaDOS

Buffer Commands

...

KS Kill Source Erases the Source Buffer by moving the EOF pointer
O Old Recovers a recently erased Source Buffer and set the first character to ";"
CL Copy to Linker Buffer

Appends linkable code from the Object Code Buffer to the Linker Buffer

WARNING The CL command erases the Source Buffer

KL Kill Linker Buffer Erases the Linker Buffer
H How big

Lists the memory areas of the Workspace, the Source Buffer and any non-empty buffers:

SEKA>H Work 047B04 057B04 65536 Src 047C82 047D78 246

Line Edit Commands

The Line Edit Mode lets you edit the Source Buffer on a line-by-line basis.

Command Mode Line Edit Mode commands:

E Edit Edits the line pointed to by the CLP
T<l=1> Target Moves the CLP to line <l>
B Bottom Moves the CLP to the last line
U<l=1> Up Moves the CLP <l> lines up
D<l=1> Down Moves the CLP <l> lines down
P<l=1> Print Lists <l> lines from the CLP down and moves the CLP <l>-1 lines down
Z<l=1> Zap Deletes <l> lines from the CLP down and renumbers any subsequent lines
L<s> Locate Finds the next case sensitive occurrance of string <s> and sets the CLP accordingly
L Locate Finds the next occurrance of string and sets the CLP accordingly
I Insert Enters Insert Mode

Entering Insert Mode inserts a new line immediately above the CLP and with the CLP line number. Any subsequent lines are renumbered. Press Return to store the new line and insert one more or Esc to return to Command Mode.

Assemble Commands

...

A Assemble Assembles the Source Buffer into the Object Buffer
A<a> Immediate Assembler Mode Enters Immediate Assembler Mode and waits for an instruction to assemble into address <a>. To assemble into the COP, use * as the address. To exit Immediate Assembler Mode, press Esc

Execution Commands

...

G[<a=PC>] Goto address

If supplied, stores address <a> in the Program Counter, and then prompts for up to 16 optional breakpoints before executing

IMPORTANT If you don't enter any breakpoints, you must end your program with an ILLEGAL instruction. If you end with an RTS, SEKA continues execution at the next address found on the stack which is usually $00000004 resulting in unpredictable behaviour

J[<a=PC>] Jump to subroutine

Executes code like the G command but halts after RTS by:

  1. Resetting the Supervisor Stack and the User Stack
  2. Pushing the Program Counter to the stack dictated by the Status Register
  3. Setting the Program Counter to an ILLEGAL instruction inside SEKA itself
S<i=1> Single step

Uses the Motorola 68000 trace facility to execute <i> instructions starting at the Program Counter excluding TRAP, LINE-A, and LINE-F calls

Register Commands

...

X Examine registers

Dumps the content of the registers to the screen:

D0=00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 A0=00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 SSP=00000000 USP=00000000 SR=A31F tsxnzvc PC=000000 BR $000008

The rows contain:

  1. Data Registers D0-D7
  2. Address Registers A0-A7
  3. Pointers SSP, USP, SR with its flags, and PC with the current instruction disassembled
X<rp> Examine and modify register or pointer Shows the value of register or pointer <rp>. To change the value, type a new value and press Return. To leave the value unchanged, just press Return

Memory Commands

...

Q[<.b|l|w>]<a=COP> Query memory Dumps 128 bytes or 64 words or 32 longwords of memory in hexadecimal and text representation starting at the COP or address <a>. Then sets the COP to the address after the last dumped address
M[<.b|l|w>]<a=COP> Examine and Modify memory Shows the value of address <a>. Type a new value and press Return or just press Return to move to the next address. To end, press Esc
F[<.b|l|w>] Fill memory Prompts for BEGIN> and END> addresses and a DATA> value to fill the memory range
C Copy memory Prompts for BEGIN>, END>, and DESTINATION> addresses and copies the memory range without eventually overwriting source data with destination data
N<a=COP> Disassembles memory into mNemonics

Disassembles 16 lines of code starting at the COP or address <a>. Then sets the COP to the address after the last disassembled address.

Note that the disassembler:

  • shows all numbers and addresses hexadecimal
  • shows registers in either order for register-only instructions such as EXG
  • only sometimes shows <.b|l|w> extensions in unambiguous places

File System Commands

Command Mode file system commands prompts for a FILENAME> and sometimes other parameters as well. SEKA automatically adds a .S extension to assembly files and a .LNK extension to linkable files.

R Read assembly file Loads an assembly file into the Source Buffer at the CLP
W Write assembly file Saves the Source Buffer to an assembly file
WO Write Object file Saves the Object Buffer to an executable file with header and relocation information
RL Read Linkable file

Appends a linkable file to the Linker Buffer

WARNING The RL command erases the Source Buffer.

WL Write Linkable file Saves the Object Buffer to a linkable file.
RI Read Image file Loads a data file into the prompted START> and STOP> memory area. To read an entire data file, set STOP> to -1
WI Write Image file Saves the prompted START> and STOP> memory area to a data file
KF Kill File Deletes the file if it exists
> copy output to file Copies all screen/printer output to a file. End the copying with another > command
V<p=""> View directory Lists the current directory. If a <p> path is supplied, sets the current directory to this path before listing the directory.

Editor Mode

Editor Mode is a full-screen text editor for the Source Buffer. To change from Command Mode to Editor Mode and back, press Esc.

WARNING SEKA erases the Clipboard Buffer when you exit Editor Mode.

Editor Mode keystrokes and shortcuts:

Ctrl+O Opens a blank line above the cursor.
Ctrl+B Selects content in the Source Buffer
Ctrl+C Cuts the selection from the Source Buffer to the Clipboard Buffer
Ctrl+P Pastes the Clipboard Buffer to the Source Buffer at the CLP
Ctrl+W Saves the Clipboard Buffer to a file

Assembling

Together, the assembler and the linker can assemble and link assembly source code and linkable object code separately or together into executable object code.

Most combinations of assembly source code, linkable object code, and the L link flag are valid. The only illegal operations is attempting to produce linkable object code from existing linkable object code.

The Source Buffer contains assembly source code? The Linker Buffer contains linkable object code? The link flag is set? The Object Code Buffer receives code?
False False False False
True False False True, executable
False True False True, executable CODE/DATA/CREL/DREL
True True False True, executable CODE/DATA/CREL/DREL
False False True False
True False True True, linkable
False True True False, illegal operation
True True True False, illegal operation

The assembler can output an assembly listing as the assembling progresses. In listings, long identifiers are truncated, and beginning-of-line comments are formatted differently than end-of-line comments.

A listing always include a Symbol Table. Symbols are alphanumeric identifiers pointing to values, and the identifier must always begin with a letter and cannot be a reserved word. You define symbols with labels or with the = or EQU directives.

The Symbol Table entries takes the form of NAME...VALUE[+]|-MACRO-. The + indicates a relocatable or external name, and MACRO replaces VALUE if NAME is a macro.

The assembler automatically upgrades out-of-range short branches to long .L branches and produces a warning. This occurs whether or not you have enabled branch optimization.

The assembler handles warnings and errors differently depending on the listing status:

You start assembling with the A command, and SEKA prompts you for OPTIONS> to produce listings and Object Code.

Assembler Options

V Outputs a listing to the screen
P or E Outputs a listing to the printer
H Pauses between listing pages and continues with Any Key
L Produces linkable Object Code
O

Enables branch optimization. The assembler adds .S branch extensions where possible. It does not shorten .L branch extensions to .S branch extensions.

WARNING The O option can extend the assembling time considerably and cause unpredictable object code.

Appendix A: Assembly Syntax

SEKA assembly syntax consist of four elements: <Label:> <Operator> <Operand> <;Comment>. Whitespace is only required between the operator and an operand, and an operand without an operator returns an error.

Labels

Labels must be suffixed with a colon.

Operators

Operators are Motorola 68000 mnemonics.

Operands

SEKA by default interprets numbers as addresses. Literal numbers are prefixed with # as in #42.

SEKA requires prefixes for hexadecimal $, octal @, and binary % numbers but not for decimal numbers.

Operand expressions can include:

Comments

Prefix comments according to their position:

Prefix with When Example
* the comment begins a line *a comment
; the comment ends a line move.l #42,d0 ;a comment

Appendix B: Assembler Directives

Assembler Directives controls the assembling.

Memory allocation and alignment
= Identical to EQU
EQU Defines a symbol with a value
console: EQU 80*24
BLK<.b|l|w> Defines a block of memory
DC<.b|l|w> Defines one or more comma separated numbers or strings
DC.B #$FF
DC.W #$FFFF
DC.L $FFFFFFFF
DC   'Hello, World'
ALIGN <n=2|4> Aligns succeding object code or data to the next word or longword boundary
ALIGN 2 aligns to word
ALIGN 4 aligns to longword
EVEN Forces the address even by defining a byte if necessary
ODD Forces the address odd by defining a byte if necessary
Operators and symbols
ILLEGAL Generates an illegal instruction
LINE_A <n> Generates a LINE_A call
LINE_F <n> Generates a LINE_F call
GLOBL Elevates one or more symbols to the global namespace. This directive is only usable when assembling with the L option and must be the first line in the source file
Conditional assembling
IF <expression> Only assembles the succeeding lines if the expression evalues to true. Can be nested up to eight levels.
ELSE Only assembles the succeeding lines if the previous IF directive evaluated to false
ENDIF Ends conditional assembling
Macro.
MACRO Begins a macro definition SYM: MACRO
?0 Defines three digits inside a macro defintion. The digits are unique for each macro call and useable for creating local labels
VARNAME?0
?<n> Refers to macro parameter <n> (1-9 are valid)
ENDM Ends a macro definition
IFB Returns true if a macro parameter is blank IFB ?2
<macro> [<n>,...] Calls a macro with optional comma separated arguments
Address modes
ORG <address> Enables Absolute Address mode
LOAD <address> Assemble object code at a specific address. Works only in Absolute Address mode
CODE Enables Relative Address mode for code segment. Begins at address 0
DATA Enables Relative Address mode for uninitialized data segment. Begins at address 0
END Ends assembling
Listing (only relevant if you started assembling with listing enabled)
LIST [<C|D|E|X>] Enables listing entirely or for specific areas only
LIST
LIST C ;macro calls
LIST D ;macro definitions
LIST E ;macro expansions
LIST X ;code extensions
NLIST [<C|D|E|X>] Disables listing entirely or for specific areas only
NLIST
NLIST C ;macro calls
NLIST D ;macro definitions
NLIST E ;macro expansions
NLIST X ;code extensions
PAGE Inserts a page break
PINIT <codes> Defines a printer initialization control code sequence
PLEN <66> Defines the printer page length
PWID <80> Defines the printer line length