Paolo Amoroso's Journal

Suite8080

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.

This video 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.

Screenshot of a Crostini Linux Minicom session showing a hello world Assembly demo running under CP/M on a Z80-MBC2 Z80 computer.

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

I extended the Suite8080 assembler to allow the ds directive to take a label as an operand. The label, which must be defined before use, may be in uppercase. I also broke into subsections the section of the documentation about the assembler limitations, as well as mentioning the limitations of org and ds.

This hopefully concludes the work to make the assembler accept uppercase identifiers such as instruction mnemonics, labels, and constants.

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

#Suite8080 #Python

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