The iLoad feature of the Z80-MBC2 homebrew Z80 computer allows uploading binary code that runs on the bare metal.

I thought it would be fun to try iLoad with some Intel 8080 code generated by the asm80 assembler of Suite8080, the suite of 8080 Assembly cross-development tools I'm writing in Python. But the code crashed the Z80-MBC2, uncovering a major asm80 bug.

It all started when, to practice the toolchain and process, I started with a Z80 Assembly demo that comes with the Z80-MBC2, which prints a message to the console and blinks one of the devices's LEDs. I assembled the program with the zasm Z80 and 8080 assembler, uploaded it via iLoad, and successfully ran it.

Next, I ported the blinking LED demo from Z80 to 8080 code and assembled it with asm80. But when I ran the demo on the Z80-MBC2, it crashed the device.

The baffling crash left me stuck for threee months, as I had no tools for debugging on the bare metal and there were only a few vague clues.

I carefully studied the less than a hundred lines of code and they looked fine. To isolate the issue I cut the code in half, leaving the part that prints a message to the console, and transforming the blinking demo into this bare.asm hello world for the bare metal:

OPCODE_PORT     equ     01h
EXEC_WPORT      equ     00h
TX_OPCODE       equ     01h
EOS             equ     00h
CR              equ     0dh
LF              equ     0ah


                org     0h

                jmp     start

                ds      16
stack:


start:          lxi     sp, start
                lxi     h, message
                call    puts

                hlt


message:        db      CR, LF, 'Greetings from the bare metal', CR, LF, EOS


puts:           push    psw
                push    h
puts_loop:      mov     a, m
                cpi     EOS
                jz      puts_end
                call    putc
                inx     h
                jmp     puts_loop
puts_end:       pop     h
                pop     psw
                ret


putc:           push    psw
                mvi     a, TX_OPCODE
                out     OPCODE_PORT
                pop     psw
                out     EXEC_WPORT
                ret

                end

The constants at the beginning define the addresses of the output ports, the opcode for sending a character over the serial line, and a couple of control characters. Next, the program sets up the stack and iterates over the output string to print every character.

The simplified demo program still crashed the Z80-MBC2, forcing me back to the drawing board.

Then I had an epiphany. What if the binary code asm80 generates is different from zasm's?

I fired up the dis80 disassembler of Suite8080 and compared the output of the assemblers. Sure enough, the difference jumped at me: the destination addresses of all the branches after the label message are off by 5 bytes.

The instructions branch to addresses 5 bytes lower, so the call to puts executes random string data that chrashes the device. The last correct address asm80 outputs is that of the label message. The address of the next one, puts, is wrong and leads to the crash.

Indeed, the same demo code assembled with zasm ran fine on the Z80-MBC2 and printed the expected message. This confirmed my hunch.

What now?

The next step is to find the bug in the Python source of asm80, which I'm developing with Replit. Although Replit provides a debugger, I won't use it. The tool is not well documented and I'm not sure how it works. In addition the Replit debugger is best suited to code started from the run button. This is inconvenient for command line programs like the Python scripts of Suite8080.

Therefore, I'll take the opportunity to use Python's native debugger pdb, which I always wanted to try in a real project. I played with pdb a bit and it looks easy to use, with all the commands and options handy.

Let's see if pdb can help me pinpoint the bug in the Python code.

#Suite8080 #z80mbc2 #Assembly #Python

Discuss... Email | Reply @amoroso@fosstodon.org

I ported to Intel 8080 Assembly the Z80-MBC2 Z80 code of the led blink demo, assembled it with the Suite8080 assembler, and uploaded the HEX binary to the Z80-MBC2. Instead of printing a message to the console and blinking the User led, the program made the led turn on and the board reset, booting up the default operating system.

I have no tools to debug software that runs on the bare metal. So the next step is to investigate these clues, starting from a comparison of the Z80 and 8080 sources.

#Assembly #z80mbc2 #Suite8080

Discuss... Email | Reply @amoroso@fosstodon.org

I develop programs for the Z80-MBC2 in Intel 8080 Assembly with the Suite8080 8080 assembler. Aside from the binary compatibility, the Z80-MBC2 is a Z80 system, so I wondered what Assembly mnemonics and register set the CP/M development tools work with.

It turns out my favorite CP/M debugger, the SID symbolic debugger, comes in two versions specialized on the CPU, SID and ZSID.

SID accepts as input and outputs 8080 mnemonics and registers, ZSID Z80 mnemonics and registers. For example, in this CP/M 3.0 SID session on the Z80-MBC2 I loaded my Twirl 8080 program and disassembled it with SID's l (list) command:

A>sid f:twirl.com
CP/M 3 SID - Version 3.0
NEXT MSZE  PC  END
0180 0180 0100 D4FF
#l
  0100  MVI  C,09
  0102  LXI  D,0139
  0105  CALL 0005
  0108  LXI  H,0142
  010B  MVI  B,08
  010D  PUSH H
  010E  PUSH B
  010F  MVI  C,09
  0111  LXI  D,013E
  0114  CALL 0005
  0117  POP  B7

The output contains 8080 mnemonics. An analogous ZSID session running the same disassembly command outputs Z80 mnemonics:

A>zsid f:twirl.com
SID VERS 1.4
NEXT  PC  END
0180 0100 CDFF
#l
  0100  LD   C,09
  0102  LD   DE,0139
  0105  CALL 0005
  0108  LD   HL,0142
  010B  LD   B,08
  010D  PUSH HL
  010E  PUSH BC
  010F  LD   C,09
  0111  LD   DE,013E
  0114  CALL 0005
  0117  POP  BC

SID thus lets me work in a 8080 environment on a Z80 system.

#z80mbc2 #Suite8080 #CPM #Assembly

Discuss... Email | Reply @amoroso@fosstodon.org

I've started writing a new Suite8080 demo in Intel 8080 Assembly, a CP/M program to move an ASCII character across the screen with vi's cursor keys h, j, k, and l. It's my first interactive CP/M program and does raw non-blocking I/O to read key presses.

#Assembly #Suite8080

Discuss... Email | Reply @amoroso@fosstodon.org

I decided what to work on next on Suite8080, the suite of Intel 8080 Assembly cross-development tools I'm writing in Python. I'll add two features, the ability for the assembler to trim trailing uninitialized data and a macro assembler script.

Trimming uninitialized data

Consider this 8080 Assembly code, which declares a 1024 bytes uninitialized data area at the end of the program:

# . . .

data:        ds    1024
             end

For this ds directive, the Suite8080 assembler asm80 emits a sequence of 1024 null bytes at the end of the binary program. The executable file is thus longer and may be slower to load on the host system, typically CP/M.

The Digital Research CP/M assemblers, ASM.COM and MAC.COM, strip such trailing uninitialized data from binaries. After asking for feedback to r/asm, I decided to do the same with asm80. I should be able to implement this optimization by adding just one line of Python, so the feature is a low-hanging fruit.

Macro assembler

asm80 can accept source files from standard input, which makes it possible to combine the assembler with an external macro preprocessor to get a macro assembler. Thanks to its ubiquity, M4 is the clear choice for a preprocessor.

Assuming prog.asm is an 8080 Assembly source file containing M4 macros, this shell pipe can assemble it with asm80:

$ cat prog.asm | m4 | asm80 - -o prog.com

The - option accepts input from standard input and -o sets the file name of the output binary program.

The other Suite8080 feature I'm going to implement is a mac80 helper script in Python to wrap such a shell pipe and make assembling macro files more convenient. In other words, syntactic sugar wrapping asm80 and M4.

The script will use the Python subprocess module to set up the pipe, feed the proprocessed source to the assembler, and not much else.

#Suite8080 #Python

Discuss... Email | Reply @amoroso@fosstodon.org

It all started when I added a new Intel 8080 Assembly demo to Suite8080. Pushing the commit to the GitHub repo triggered a rebuild of the project documentation hosted on Read The Docs, which failed.

I maintain the Suite8080 documentation with Jupyter Book and publish it to Read The Docs with Sphinx as the backend.

Over the previous months, while my work on Suite8080 was on hold, some backward incompatible Jupyter Book update broke the Suite8080 documentation configuration. I had no idea what to do, so I opened a Read The Docs issue. After some troubleshooting with the help of Manuel Kaufmann, Benjamin Balder Bach contributed a Suite8080 pull request that fixed the issue.

Benjamin's patch has an additional advantage. I no longer have to manually edit conf.py to let sphinx.ext.autodoc discover the project's Python packages.

#Suite8080 #Python

Discuss... Email | Reply @amoroso@fosstodon.org

I ported to CP/M Twirl, a twirling bar animation demo in Intel 8080 Assembly. I originally developed it for emuStudio, an emulator and development environment that recreates a number of classic computers and CPUs. The port runs on any CP/M system with an ANSI terminal or display.

I recorded a screencast that shows Twirl running under CP/M 3.0 on the Z80-MBC2 computer, controlled from a Minicom terminal emulator session under Crostini Linux on my Chromebox.

How it works

The demo displays an ASCII animation of a bar twirling clockwise at the home position of the console, i.e. the top left corner. After clearing the screen, Twirl repeatedly moves the cursor to the console home, prints the current animation frame, and checks for key presses to decide whether to terminate.

Although visually simple, the program demonstrates some key Assembly programming techniques such as looping, calling BDOS functions, and doing output with ANSI escape codes.

Porting

The original Twirl runs on a virtual Altair 8800 computer with a Lear Siegler ADM-3A terminal emulated by emuStudio.

However, I designed the program intending to port it to CP/M. The necessary work consisted in replacing the Altair-specific I/O rutines with equivalent BDOS calls for printing a single character (function 02h) and a string (09h) of ANSI escape codes, and checking the console status for key presses (0bh).

The program logic works as is, but I had to modify the CP/M version for defining the appropriate constants and ANSI escape strings, as well as adapting to the execution environment of the operating system and returning control to it.

Building and running

For me, the whole point of writing programs like Twirl and getting Z80 hardware is to use Suite8080, the suite of Intel 8080 Assembly cross-development tools I'm writing in Python. The CP/M port is a new Suite8080 Assembly demo I built from source on Linux with asm80, the Suite8080 assembler:

$ asm80 twirl.asm

I tested the resulting 74 bytes twirl.com executable under CP/M 2.2 with the CP/M software emulators ANSI CP/M emulator and z80pack.

Running the demo at the CP/M prompt is straightoward:

B>twirl

Pressing any key quits Twirl and returns control to the operating system.

To exeute Twirl on actual hardware I converted twirl.com to Intel HEX format with z80pack's bin2hex tool, then transferred the twirl.hex file to the Z80-MBC2 under CP/M 3.0.

It was really rewarding to see Twirl come to life on a real Z80 computer and get a sense of its performance.

The code

Here is the full code of the CP/M port of Twirl:

; Twirling bar animation.
;
; Runs on CP/M with an ANSI terminal. Press any key to quit the program.


TPA        equ      100h
BDOS       equ      0005h
WRITESTR   equ      09h                ; Write string
WRITECHR   equ      02h                ; Write character
CONSTAT    equ      0bh                ; Console status

FRAMES     equ      8                  ; Number of animation frames


           org      TPA
            
           mvi      c, WRITESTR
           lxi      d, cls             ; Clear screen
           call     BDOS

loop:      lxi      h, anim            ; Initialize frame pointer...
           mvi      b, FRAMES          ; ...and count

loop1:     push     h
           push     b
           mvi      c, WRITESTR
           lxi      d, home            ; Go to screen home
           call     BDOS
           pop      b
           pop      h

           push     h
           push     b
           mvi      c, WRITECHR
           mov      e, m               ; Print current frame
           call     BDOS
           pop      b
           pop      h

           push     h
           push     b
           mvi      c, CONSTAT         ; Get console status
           call     BDOS
           pop      b
           pop      h
           ora      a                  ; Key pressed?
           jnz      exit               ; Yes

           inx      h                  ; Point to next frame
           dcr      b                  ; One fewer frame
           jnz      loop1

           jmp      loop

exit:      ret


cls:       db       1bh, '[2J$'        ; ANSI clear screen: ESC [ 2 J
home:      db       1bh, '[H$'         ; ANSI go to screen home: ESC [ H
anim:      db       '|/-\|/-\'         ; 8 frames

           end

The program represents the animation as the string |/-\|/-\, a sequence of ASCII characters that show the bar at various steps of the rotation.

After clearing the screen, Twirl begins the main loop loop: by initializing the frame pointer and count. An inner loop loop1: prints each animation frame, i.e. the characters of the animation sequence.

The inner loop moves the cursor to the home position and prints the current frame. Then it updates the frame pointer and count, and checks whether a key was pressed. In case of a key press the inner loop exits the program, otherwise it jumps back to the beginning of the main loop.

#Assembly #retrocomputing #Suite8080 #z80mbc2 #CPM

Discuss... Email | Reply @amoroso@fosstodon.org

In the Crostini Linux Minicom terminal emulation session of this screenshot, a hello world Intel 8080 Assembly program run under CP/M on the Z80-MBC2 Z80 homebrew computer, printing the string Greetings from Suite8080 to the console.

It may not seem like much, but it's a personal achievement I'm proud of.

The demo program comes with Suite8080, a suite of Intel 8080 Assembly cross-development tools I'm writing in Python. I created the demo, assembled it with my own assembler, and run it on actual hardware. Just a few months ago I didn't think I could do this.

Running the demo also helped me put together and test a cross-development toolchain based on Suite8080. For example, I learnt how to transfer files via XMODEM from Crostini to the Z80 board.

I can't wait to use the toolchain to develop more code for the Z80-MBC2.

#Suite8080 #z80mbc2 #sbc #CPM

Discuss... Email | Reply @amoroso@fosstodon.org

What I anticipated and planned for is happening.

After the great momentum of the initial work on Suite8080, I set it aside for a couple of months. Now I'm about to resume work on the project and wonder how hard it'll be to dive back into the Python code and continue development.

I tried to prepare for this by documenting the system and commenting the code. I also took many notes on to-do items, features I'd like to add, and ways to implement them. At a few thousand lines, the code base is small and I hope it won't be too difficult to understand and change.

Still, I'm a Python beginner and my code is tightly coupled, fragile, not modular, and hard to extend.

Suite8080 is a suite of Intel 8080 Assembly cross-development tools I'm writing in Python.

#Python #Suite8080

Discuss... Email | Reply @amoroso@fosstodon.org

I released version 0.5.0 of Suite8080, a suite of Intel 8080 Assembly cross-development tools I'm writing in Python. Although still in an early stage, this version makes Suite8080 gain enough functionality to be useful in a variety of Assembly applications.

In my next steps I'm going to focus on two areas of improvement.

First, I'll write more 8080 programs to process with the Suite8080 assembler and run on emulated CP/M systems or actual hardware. After all, this is the fun part I began the project for.

The Suite8080 Python sources are still a tangled mess of tightly-coupled, unencapsulated, beginner code with global state that makes it difficult to add new features or change existing ones. Therefore, the other area of improvement I'll work on is a major redesign. This should make the code easier to work with and extend.

#Python #Suite8080

Discuss... Email | Reply @amoroso@fosstodon.org