HC Software Development Kit for Retro Computing

Cross-compiler tools for retro computing.

_{Executed with make test_emu or make test && bin/msxdosemu -diska tests/ -step tests/z80-test-0.com test.txt}

Tools ready to use:

• Assembler
• Linker
• Librarian
• Project Builder

Tools in development (Early test only):

• RetroLang (Simple programming language for 8 bit)
• MSX-DOS 1.0 / CP/M 2.2 Emulator

Links:

• Site e Documentação em Português
• Site and Documentation in English
• RetroLang (In Alpha) Documentation
• Hackaday Article

TODO List (Pending for 2.0 | Early April/26)

• MSX-DOS 1.0 (CP/M 2.2 Compatible) Emulator (In progress)
  • Screen/Keyboard I/O to VT110 TTY Mode (In progress)
  • Screen 40x24 with Debug Mode (In progress)
  • MSX-BIOS ABI (Planned)
    • Screen ABI (Planned)
  • MSX Hardware Emulation (In progress)
    • Screen 40x24 Direct Manipulation (In progress / Testing)
  • Tests:
    • BASCOM SAMPLE.COM (Fail Try call WRSLT??)
    • M80.COM (Fail try output to port 0)
    • L80.COM (Fail Try call 5 0x13 function)
    • BASCOM.COM (Run / Testing)
    • MBASIC.COM (Fail to start)
• RetroLang Compiler (In progress)
  • Implement all planned pointers (In progress)
  • Structure Support (Planned)
  • Array Support (Planned)
  • 8086 Target and Libraries
    • 8086 Target (Done)
    • DOS Library (Planned)
    • BIOS-only Library (Planned)
  • Z80 Target and Libraries
    • Z80 Target (In progress / Testing)
    • Common Math/Logic Runtime Library (Done / Testing)
    • CP/M 2.2 Library (In progress)
    • MSX-DOS 1.0 Library (Planned)
  • 8080 Target and Libraries (Planned for 3.0)
• HC Builder
  • Embbed SDK BIN/Libraries/Include Path on install (Planned for 2.1)
• HC Assembler
  • 6502 Target Support (Planned for 3.0)
• Integration on VSCode (Planned for 3.0)

Supported Targets

• 8080: Intel 8080 or Compatibles
• 8085: Intel 8085 or Compatibles
• 8086: Intel 8086/8088 or Compatibles (Single segment executable output)
• Z80: Zilog Z80 or Compatibles

Supported Hosts - Pre-compiled distribution

• macOS - Intel/Apple Silicon:
  • hcsdk-macos-v??.??.??-setup.pkg: macOS Installer
  • hcsdk-macos-v??.??.??.tgz: macOS Binaries
• Windows - Intel 64 bits:
  • hcsdk-win-v??.??.??.zip: Windows Binaries
  • hcsdk-win-v??.??.??-setup.exe: Windows Installer
• Windows - Intel 32 bits:
  • hcsdk-win32-v??.??.??.zip: Windows Binaries
  • hcsdk-win32-v??.??.??-setup.exe: Windows Installer
• Linux - Intel
  • hcsdk-linux-v??.??.??.tgz: Linux Binaries
  • hcsdk-linux-v??.??.??.deb: Debian/Ubuntu-based Package
• DOS - Pentium or Compatible
  • hcsdk-dos-v??.??.??.zip: DOS Binaries

Tested Hosts - Build with make

• Linux - ARM
• FreeBSD - Intel
• OpenBSD - Intel

Install

Installing on /usr/local/bin:

make all
sudo make install

How to use (8086 example)

• Create a example file (example.s):

  section text
  global _start
  _start:
      int 0x20
  

• Assemble to object file

  hcasm-8086 -o example.obj example.s
  

• Link to .com file

  hclink-bin -text 0x100 -o example.com example.obj
  

Development on macOS

Installing the minimum requirements for development:

brew tap messense/macos-cross-toolchains
brew install z80dasm dpkg llvm cmake xwin mingw-w64 x86_64-unknown-linux-gnu msitools nsis

Install last DJGPP version from GitHub to /usr/local/djgpp

Execute sudo xattr -r -d com.apple.quarantine /usr/local/djgpp

Generating distribution files:

make distro

MSX-DOS 1.0 (CP/M 2.2) Emulator

Implement MSX-DOS 1.0 Compatible Emulator with embedded Debugger.

Emulator supports function key shortcuts with modifier keys (ALT and CTRL).
For example: F12, CTRL+F12, ALT+F12.

Usage:

# Execute cat.com with test.txt as argument
msxdosemu cat.com test.txt
# Execute cat.com with test.txt as argument
# test.txt will be read from new A: path: other/dir/
msxdosemu -diska other/dir/ cat.com test.txt
# Run in debug mode cat.com with test.txt as argument
# will wait next breakpoint (ld b,b) to change to debug step mode
msxdosemu -debug cat.com test.txt
# Run in debug step mode cat.com with test.txt as argument
msxdosemu -step cat.com test.txt
# Run in debug mode cat.com with test.txt as argument
# will wait next breakpoint (ld b,b) or IP=0x103 to change to debug step mode
msxdosemu -skip 0x103 cat.com test.txt

MSX / MSX-DOS Supported Features:

• MSX-DOS CALL 5 ABI
• MSX-DOS / CP/M FCB File I/O
• Console I/O
• Prefilled FCBs at 0x5c and 0x6c with filenames in arguments
• Z80 CPU

Not implemented but planned features:

• MSX-BIOS Calls
• I/O Ports
• Slots and Memory Mapping
• MegaRAM / Mapper
• MSX-DOS 2.0 Support
• Windows Console Support

Not supported features:

• MSX Sound Output
• MSX-DOS CALL 5 ABI C=0x05 - Write Char to Printer
• MSX-DOS CALL 5 ABI C=0x11 - Search FCB
• MSX-DOS CALL 5 ABI C=0x12 - Search Next FCB
• MSX-DOS CALL 5 ABI C=0x13 - Delete file FCB
• MSX-DOS CALL 5 ABI C=0x18 - Get Login Vector

RetroLang for Retro Computing

Low Level Programming Language inspired in Ruby, BASIC, T3X and Pascal.

Don't use. Pre-alpha Compiler

HC Assembler for Retro Computing

Inspired in NASM Source Code Format.

Intel 8080 / 8085 Support

• Support BC/DE/[BC]/[DE] or B/D/[B]/[D] on 16 bit operations

  ; all four generate the same opcode
  stax bc ; modern format
  stax b ; old school format
  stax [bc] ; nasm-like format
  stax [b] ; old school nasm-like format
  

• Support M/[HL]/[M] on pointer operations

  ; all tree generate the same opcode
  mov a, m
  mov a, [m]
  mov a, [hl]
  

Zilog Z80 Support

• Use [] as address markers \

  ld a, [0x1234]
  ld a, [bc]
  

Intel 8086/8088 Support

• Alow command prefixes and some argument prefixes:

  ; command prefixes
  cs mov ax, [label]
  rep movsb
  ; argument prefixes
  mov word [0x123], 123
  mov [0x123], word 123
  call near label
  call far label
  je short label
  je near label
  je far label
  ; NOT SUPPORTED PREFIXES:
  mov ax, [cs:label] ; DO NOT USE
  

• Allow jCC near and far (8086/8086 full compatible)

  je label_with_offset_less_than_128_bytes
  je near label_with_offset_greater_than_128_bytes
  je far segment:offset
  je far label_in_other_segment ; (not supported in all link output formats)
  

• Allow LOOP/LOOPZ/LOOPE/LOOPNZ/LOOPNE/JCXE/JCXZ/JECXZ/JECXE near and far (8086/8086 full compatible)

  loop label_with_offset_less_than_128_bytes
  loop near label_with_offset_greater_than_128_bytes
  loop far segment:offset
  loop far label_in_other_segment ; (not supported in all link output formats)
  

Source Code Format

label: mnemonic arg1, arg2 ; comment

Labels

global _start   ; export _start label
_start:
.sublabel:
main:
.sublabel:
    mov ax, [.sublabel]
    mov ax, [main.sublabel]
    mov ax, [_start.sublabel]

Constants

const_123: equ 123
const_456 equ 456
const_math equ 1+2*3
struct_test: equ 2 ; size
    .field1: equ 0 ; offset
    .field2: equ 1 ; offset

section data
    obj_test: resb struct_test

section text

    mov ax, const_math ; simple example
    mov al, [obj_test + struct_test.field1]
    mov si, obj_test
    mov bl, [si+struct_test.field1]

Sections

Common section order:

• text section
• data section
• bss section

Input code:

section data
    db 0x56
section text
    db 0x12
section bss
    db 0x9a ; Invalid command for bss, used only as an example.
section data
    db 0x78
section text
    db 0x34

Binary output (Hexadecimal view):

TEXT     | DATA    | BSS
0x12 0x34 0x56 0x78 0x9a

Data/Address Reference/Address Access

section data
    var: dw 0x1234
    structure:
        .field1: db 0x12
        .field2: db 0x34
section text
    ; data
    mov ax, 0x1234 ; hexadecimal
    mov bx, 1234 ; decimal
    mov cx, 0b10010001 ; binary
    mov dx, 0o777 ; octal
    mov si, 0777 ; octal
    ; address reference
    mov si, var
    mov di, structure.field1
    ; addres access
    mov al, [structure.field1]
    mov [structure.field2], bl

HC Librarian for Retro Computing

Add/Replace objects into library

hclib test.lib test1.obj test2.obj test3.obj

HC Linker for Retro Computing

Output formats

• bin: Flat Binary
• rex: Relocatable Executable

HC Linker for Flat Binary

Supported arguments:

• -text [OFFSET]
  Define start of text section
• -data [OFFSET]
  Define start of data section
• -bss [OFFSET]
  Define start of bss section
• -align [OFFSET]
  Define align of all sections

# Generate CP/M .COM file
hclink-bin -o test.com -text 0x100 test.obj lib.lib
# Generate Generic .BIN file
hclink-bin -o test.bin test.obj lib.lib
# Generate MSX Simple .ROM file
hclink-bin -o test.rom -text 0x4000 -bss 0xc000 test.obj lib.lib

HC Linker for Relocatable Executable

Supported arguments

• -align [OFFSET]
  Define align of all sections

hclink-rex -o test.rex test.obj lib.lib

HC Builder

Configuration example (.prj file):

[config] ; optional section
dump = yes ; optional (default: no) - dump object dump from assembly
verbose = yes ; optional (default: no)
sdk_path = ./ ; optional (default: empty string) - hcsdk tools path

[files:z80] ; use files:ARCH
main.s ; file list

[libs] ; optional section (allow objects or library)
runtime.lib
single.obj

[libs:start] ; optional section (set start object from external runtime)
start.obj

[link:rel