Assemble and Run

New to programming entirely? You'll have a smoother time starting with General Programming first — this track assumes you've already met variables, loops and subroutines somewhere. If you have, in any language, you're in the right place.

This is the Primer — Meet the Machine. Its whole job is to make the Commodore Amiga stop feeling like magic, one small idea at a time. No game yet, no sprites, no clever code. Just you and the machine, getting introduced.

If you've come from one of the 8-bit Primers — Spectrum, C64 or NES — a word before we start: expect more to be new here than to carry over. Those machines ran 8-bit CPUs (the Z80, the 6502). The Amiga runs the Motorola 68000 — a 16/32-bit processor with a different instruction set, far more registers, and a family of custom chips that do the graphics and sound for you. The way of thinking transfers. Almost none of the actual instructions do. That's the point of meeting it properly.

And the first idea is the smallest one there is: there's a build step, and it ends in a floppy disk. A tool called an assembler (vasm) turns your text into a program, and then that program is written onto a bootable floppy-disk image (an .adf) — because that's how an Amiga loads and runs software. Write, assemble, master to disk, run. This unit is that loop, done once, with the simplest visible result the Amiga can give.

What you'll see by the end

A red screen. That's it — and that's the win. You wrote it, you built it, the machine did it. The moment the floppy boots, the whole screen turns red.

The harness, and the one line that's yours

On an 8-bit machine you changed a colour with a store or two. The Amiga asks for more — not because it's harder to think about, but because there's a whole multitasking operating system in the way, and three custom chips that won't lift a finger until you tell them to.

So the first thing a bare-metal Amiga program does is take the machine away from the operating system — switch off its interrupts and its DMA, so nothing else is touching the hardware. Then, instead of drawing the screen with the CPU, you hand a tiny list of instructions to the Copper — a co-processor inside the Amiga that runs in step with the video beam — and switch the display DMA on. The Copper paints the screen for you.

All of that is ceremony: the same every time. So we wrap it in a harness you type once and treat as a sealed box. Later units pry it open — the Copper is Unit 7, the registers are Unit 2. For now, your eye goes to one place: the line in the Copper list that names the colour.

The program

This is the whole thing. Almost all of it is the harness; the one line between the YOUR CODE markers is yours:

;──────────────────────────────────────────────────────────────
; Meet the Machine (Amiga) - Unit 1: Assemble and Run
;
; Everything outside the YOUR CODE block is the harness: the ceremony the Amiga
; needs before it will show a single colour. You take the machine away from the
; operating system, hand the Copper a tiny list of instructions, and switch the
; display on. You type it once and treat it as a black box; later units open
; each part up. For now, the one line that matters is the colour.
;──────────────────────────────────────────────────────────────

CUSTOM      equ $dff000         ; base address of the custom chips

DMACON      equ $096            ; DMA control
INTENA      equ $09a            ; interrupt enable
INTREQ      equ $09c            ; interrupt request
COP1LC      equ $080            ; Copper list address
COPJMP1     equ $088            ; Copper restart strobe
BPLCON0     equ $100            ; bitplane control
COLOR00     equ $180            ; background colour register

            section code,code_c   ; code_c = Chip RAM (the Copper reads from here)

start:
            lea     CUSTOM,a5           ; a5 = $DFF000, the custom-chip base

            ; --- take the machine away from the OS ---
            move.w  #$7fff,INTENA(a5)   ; disable all interrupts
            move.w  #$7fff,INTREQ(a5)   ; clear any pending ones
            move.w  #$7fff,DMACON(a5)   ; disable all DMA

            ; --- hand the Copper our list, then switch the display on ---
            lea     copperlist,a0
            move.l  a0,COP1LC(a5)       ; tell Agnus where the list is
            move.w  d0,COPJMP1(a5)      ; strobe: start the Copper
            move.w  #$8280,DMACON(a5)   ; DMA on: master + Copper

forever:
            bra.s   forever             ; hold the picture (nothing to do)

;──────────────────────────────────────────────────────────────
; The Copper list: a tiny program the display co-processor runs.
; It sets up a screen with no bitplanes, so the whole display is
; just the background colour.
;──────────────────────────────────────────────────────────────
copperlist:
            dc.w    BPLCON0,$0200       ; 0 bitplanes - show only the background

            ; ----------------------------------------------- YOUR CODE START
            dc.w    COLOR00,$0f00       ; background colour = red ($0RGB)
            ; ------------------------------------------------- YOUR CODE END

            dc.w    $ffff,$fffe         ; end of the Copper list

Look only at the YOUR CODE block, down in the Copper list:

dc.w    COLOR00,$0f00       ; background colour = red ($0RGB)

That hands the Copper one instruction: put $0f00 into the background-colour register. Amiga colours are written $0RGB — three four-bit channels, red/green/blue — so $0f00 is "red all the way up, no green, no blue." With no bitplanes switched on, the whole screen is just that background colour. You don't need to follow the rest yet; that's what a harness is for.

The forever: bra.s forever near the top holds the picture still — it branches to itself, endlessly. Without it the CPU would run on into whatever bytes came next. (We'll meet that idea properly at the end of the Primer.)

Assemble, master, and run

This unit ships with a Makefile, so the whole build is one command from the unit's directory:

make

That does two jobs: it runs vasm to assemble screen.asm into an Amiga program, then it writes that program onto a bootable floppy image, screen.adf, with a boot block and a startup that runs your program. (You'll see the two steps scroll past.) Load screen.adf in your emulator as the disk in drive DF0: and the screen is red the moment it boots.

You just did the whole cycle: write → assemble → master → run. Everything else in this course is that loop, again and again, with more interesting things in the middle.

Try this: a different colour

Change the $0f00 in the Copper list to another $0RGB colour, then make and run again. A few to try: $00f0 green, $000f blue, $0ff0 yellow, $00ff cyan, $0f0f magenta, $0fff white, $0000 black. Each digit is a channel from 0 to F. Predict the colour before you run it, then check. (This is the loop again — change, build, run.)

Try this: a darker shade

Colours don't have to be full-strength. Try $0800 (half-red), then $0400, then $0200. Same hue, dimmer each time — because you're turning the red channel down a step at a time. The Amiga gives you sixteen levels per channel, which is how its palettes get so much subtler than an 8-bit machine's handful of fixed colours.

If it doesn't work

• vasm reports an error and make stops. Read the line number — usually a mistyped instruction or a stray character. Fix that one line and make again.
• make fails at the disk step. That's the .adf mastering. Check you ran it from this unit's directory, and that the toolchain image is available.
• The screen is black, not red. The colour didn't reach the Copper. Check the one line is dc.w COLOR00,$0f00 — the register name, a comma, then the $0RGB value.
• The screen is grey / shows the insert-disk hand. The disk didn't boot your program — re-run make to rebuild screen.adf, and make sure it's the disk in DF0:.

What you've learnt

Writing Amiga assembly means write → assemble → master → run — your program ends up on a bootable floppy, and you've now been all the way round the loop once. You've also met the shape of the machine: a bare-metal Amiga program takes the hardware away from the operating system, then lets the custom chips — here, the Copper — do the drawing. Today the Copper painted one colour: red.

What's next

You wrote a value into a register without stopping to meet how. Next — MOVE Is the Verb — we slow down and meet the 68000's workhorse instruction. Where the 8-bit machines had separate "load" and "store", the 68000 has one instruction that moves a value from almost anywhere to almost anywhere — and a bank of registers far roomier than anything an 8-bit chip offered.