Using the Assembly Lab

The Assembly Lab is a Tatung Einstein in your web browser with a code editor underneath it. You write Z80 assembly language, press one button, and a moment later it is running on the Einstein above. Nothing needs installing, and the lab never sends your code anywhere: it is assembled and run inside your own browser.

It is also a window into the machine. You can stop your program before any instruction, run it one instruction at a time, and watch the registers, the flags and the memory change as it goes. This guide covers every part of it, in the order you are likely to meet them. If you are new to assembly language, the Z80 Assembly course starts from the beginning, and every one of its programs can be opened in the lab.

The Machine

At the top of the page you choose the machine: the Tatung Einstein TC-01 or the Tatung Einstein 256. The lab starts on the TC-01, which is the machine the Z80 Assembly course is written for. The Einstein 256 Primer needs the 256, and its programs will not work on the TC-01. Opening one of the Primer's examples switches the machine for you.

Changing machine starts a fresh Einstein. While it starts, a spinner covers the screen, first while the emulator loads and then while the Einstein boots to its prompt. The Run buttons wake up when it is ready.

The box at the very top explains the lab in a few lines. Hide This folds it away, and How It Works brings it back.

Writing Code

The editor is the dark panel at the bottom of the page. It starts with a short program that prints HELLO, which is the first program in the course.

• Colours. Instructions, registers, numbers, text in quotes, directives such as ORG and DEFB, and comments each have their own colour, so a typing mistake usually shows up straight away.
• Line numbers run down the left.
• Addresses. The green column beside the line numbers is the memory address each line assembles to, in hex. The lab assembles your program quietly half a second after you stop typing, so the column keeps up as you write. A line that makes no code, such as a comment or a blank line, has no address.
• Tab inserts a tab, and Enter keeps the indent of the line above, so instructions stay lined up.
• Ctrl+Enter (Cmd+Enter on a Mac) runs the program without reaching for the mouse.
• Under the editor, the lab shows the line and column the cursor is on. Drag the editor's bottom right corner to make it taller; the lab remembers the height.
• Theme changes the editor's colours: Modern Dark, Einstein Blue, Green Screen, Mainframe, Amber and Paper.

Running a Program

Run assembles your program and runs it on the Einstein at full speed. The button shows a spinner while it works, and the line under the screen says what happened: how many bytes your program assembled to, and that it is running.

The lab assembles with GNU z80asm 1.8, the same assembler the course uses, and runs your program as a .COM file at address 0100h, exactly as the course's VS Code extension does. Every program needs ORG 256 (or ORG 100h, the same number) at the top for that reason.

When your program finishes it returns to the Einstein's built in monitor, MOS, which prints a line of register values and gives you its > prompt. S3 of the course explains that line in full.

Click the screen to type into the Einstein. Keys you press then go to the machine rather than to the editor, which is what a program that reads the keyboard needs.

When It Does Not Assemble

If the assembler finds a mistake, nothing runs. A pink box appears under the editor listing each problem, and the tab of any file with a problem is marked.

Click the line number in a problem to jump straight to that line in the editor. The box clears itself as soon as the program assembles again.

Opening an Example

Open an Example lists every program from the lab's two courses: the 47 programs in Z80 Assembly for the Tatung Einstein, and the 23 in the Einstein 256 Primer. They are grouped by section, with the number of lines in each, and you can choose a course at the top or search them all by name.

Opening an example replaces the files in the editor, so download anything you want to keep first. Examples that use more than one file, such as River Run in the Primer, open with all their files in tabs.

Several Files

A bigger program is easier to manage in more than one file. The tabs above the editor are your files.

• main.asm is always the first tab. It is the program: assembly starts there, and it cannot be renamed or deleted.
• + New File adds a file and asks for its name straight away. Names are lower case letters, digits, _ or -, ending in .asm, .inc or .z80. One folder is allowed, as in screens/level1.asm. You can have up to sixteen files.
• Double click a tab to rename it. If main.asm includes the file, change its include line too.
• × deletes a file. If the file has anything in it, the × turns into Delete? and a second click confirms.

A new file does nothing until main.asm brings it in with a line such as:

        include "sprites.asm"

The assembler then reads that file at that point, as if its text were typed there. The address column and the problems box work across all the files, and a problem names the file it is in.

Stepping Through a Program

This is the heart of the lab. Run in Steps loads your program and stops it before its first instruction. The button then becomes Next Step, and each press runs one more instruction and stops again.

While your program is stopped:

• The line it will run next is marked with an arrow beside its line number in the editor, and the status line names it.
• Step, under the screen, does the same as Next Step. The box beside it sets how many instructions each press runs; it starts at 1. Next Step uses the same number.
• If you press faster than the Einstein answers, the lab counts the presses and runs them all.
• Continue lets the program carry on at full speed.

Stepping stops only inside your own program. When your program calls one of the Einstein's own routines, such as RST 8 to print a character, one step runs the whole routine and stops at your next instruction. When your program finishes, the lab says so, and Next Step starts it again from the first line.

Breakpoints

Click a line number to set a breakpoint, marked in red. Run then goes at full speed until it reaches that line, and stops before it, so you can step from there. Click the number again to remove it. A breakpoint needs a line that holds an instruction, and you can have up to eight.

Pause and Reset

Pause stops the Einstein wherever it is, which may be inside MOS rather than your program; it then becomes Continue. Reset restarts the Einstein back to its MOS prompt, which is useful if a program has run away and will not stop.

The Registers Panel

Registers, under the screen, opens the panel that shows what is inside the Z80. It has two views, chosen at its top right.

Programmer

The Programmer view shows the registers you use when you write a program, laid out to show how they fit together. It fills in when your program is stopped, which is what Run in Steps is for.

• A, the accumulator, comes first, because most arithmetic happens there.
• The flags are shown as the eight bits of the F register, each one a 1 or a 0, with its name above: S (sign), Z (zero), H (half carry), P/V (parity or overflow), N (subtract) and C (carry). Bits 5 and 3 are greyed because nothing uses them. Point at a flag for what it means. A flag holds the result of the last instruction that sets flags, not of the last line, and many instructions, such as LD, leave the flags alone.
• BC, DE and HL are each shown above their two halves. BC is B and C together, B being the high byte; change B and BC changes with it.
• IX, IY, SP and PC sit alongside. PC, the program counter, is the address of the next instruction, and SP the top of the stack.
• Yellow marks every value that changed in the step you just took.
• Next: under the registers names the line about to run; click it to go there in the editor.

When your program is not stopped, the boxes stay in place but grey, holding their values at the last stop, and a line above them says what to press.

Live

The Live view shows everything, all the time, as fast as it changes.

• Your Registers holds the same registers as the Programmer view, the flags, and the top of the stack.
• Behind the Scenes holds the alternate set, a spare copy of AF, BC, DE and HL that the EXX and EX AF,AF' instructions swap in, and the registers that run the processor itself: I and R, the interrupt mode, and whether interrupts are on.

When your program is not running, the registers are still busy, because the Einstein's own software keeps running while it waits at the prompt. The note above the Live view tells you whose registers you are looking at.

Click any register value to open it in the number converter, described below.

Hex, Decimal, Binary and Character

Every value in the lab is a number, and a number can be written several ways. The ticks along the top of the Registers and Memory panels choose which you see:

Tick any combination and the lab shows each value in every form you have ticked, side by side. The two panels share one set of ticks, so changing one changes the other. Hex alone is the default, and the lab remembers your choice. Point at any value to see it in every form at once.

The Memory Panel

Memory opens a view of 128 bytes of the Einstein's memory, starting at address 0100h, where your program goes.

• Address or label. Type an address in hex, such as 8000 or 8000h, or the name of a label in your program, and press Go.
• PC, SP, HL, IX follow that register, so the view moves with it as you step: PC keeps the next instruction in view, SP the stack, HL and IX whatever they point at. Click the button again to stop following.
• ▲ and ▼ move back or on by 128 bytes.
• Tints. Your program's bytes are tinted blue, the bytes of the next instruction are outlined, and bytes that changed since the last look are yellow.
• Formats. Each row has one line for every format you have ticked, labelled hex, dec, bin and chr. With Binary ticked a row holds 8 bytes instead of 16, so it still fits. In the chr line, ␣ is a space, and a byte with no printable character is left blank.

Two things surprise almost everyone the first time, and both say something true about the machine:

• Your whole program is in memory before it starts. The lab loads every byte of it, then runs it. So the letters of HELLO are there before the instructions that print them have run.
• Code and data are the same thing. LD A,'H' assembles to the two bytes 3E 48. 48h is the code for H, so the chr line shows an H. 3Eh is the instruction "load the next byte into A", but it is also 62, the code for >, so the chr line shows a > there too. Memory holds only numbers. Whether a byte is an instruction, a letter or a count depends only on what reads it, and the processor treats a byte as an instruction only if it is sent there to run it.

The Number Converter

Numbers opens a converter for moving between the four ways of writing a number.

• Type in any box, Hex, Decimal, Binary or Character, and the others follow as you type.
• Click a bit to flip it. Each bit is labelled with its value, so you can see a number built from its bits.
• Under the bits, the converter shows the working: how the hex and the binary each add up to the decimal, and which character the number is the code for.
• One Byte and Two Bytes choose 8 or 16 bits. Two bytes suits register pairs and addresses; Character is greyed out then, since a character is one byte.
• Clicking a register value in the Registers panel opens it here, in the right size.

The Keyboard

Show Keyboard puts the Einstein's own keyboard on the page. Click its keys to type into the Einstein. It is handy for keys a modern keyboard does not have, and on a touch screen.

Keeping Your Work

The lab keeps your files in your browser as you type, so they are still there when you come back on the same computer and browser. They are not sent anywhere, which also means they are not backed up: clearing your browser's data for the site, or using a private window, loses them. To keep a program safe, take a copy out.

• Copy Code copies the file you are looking at, ready to paste elsewhere.
• Download .asm saves the file you are looking at.
• Download DSK makes a disc image you can put on a Gotek drive and boot on a real Einstein. The disc boots XtalDOS and runs your program by itself, as MAIN.COM, and your source files are on it too.
• Download MFI makes the same disc as a .mfi, the format MAME prefers. DSK, MFI and SCP explains the difference.

The lab also remembers your settings: the machine, which panels are open, the register view, the number formats, the theme and the editor's height.

Phones and Tablets

The lab works best on a computer with a keyboard. On a phone or a tablet it says so once when it opens, then lets you carry on. The editor is cramped on a small screen, and stepping through a program beside its registers is hard to follow there.

All the Controls