Zeal8bit/Zeal-8-bit-OS

how can i add new board to it

yangkkokk opened this issue · 2 comments

yangkkokk commented

i have a diy z80 sbc

cpu:hd64r180rop
ram: 62256x2
rom:w27c512
clock:9.13mhz

can i use your boot loader ?

Zeal8bit commented

Hello @yangkkokk !

About the prerequisites

In terms of hardware, the HD64180 is binary compatible with Z80 assembly so this is possible. Currently, Zeal 8-bit OS requires the target to have an MMU which separates the 64KB of virtual memory into 4 pages of 16KB each. The HD64180 includes an MMU but it separates the address space into at most 3 pages, and not 4. I do plan to add a no-MMU configuration option which would simply require the first 16KB to contain the OS code and the rest (48KB) to be RAM.

I see that you have 64KB of RAM, so one possibility would be to copy the OS code to RAM before executing it, or mapping ROM into the first 16KB and map the rest into RAM, the HD64180 MMU should be able to do this.

Porting to a new target

Configuration and build system

Let's assume that we have the no-MMU kernel, you will need to create a new target in the target directory, which contains a unit.mk file. On Linux you can do something like

mkdir target/my_z80_sbc
cd target/my_z80_sbc
touch unit.mk

This file will tell the build system which ASM files need to be compiled, so it should contain something like:

# Add folders to the included directories
INCLUDES := ./ ./include

# Add the ASM files to assemble
SRCS := my_linker.asm my_uart.asm my_mmu.asm

# You can also add PRECMD to execute a command BEFORE the build
PRECMD := echo "Hello world!"

# You can add POSTCMD to execute a command AFTER the build
POSTCMD := echo "Assembling finished!"

You can also add a Kconfig file which will contain the configuration for your own target. These options will be shown in when using make menuconfig.

You can check the one for zeal8bit target: https://github.com/Zeal8bit/Zeal-8-bit-OS/blob/main/target/zeal8bit/Kconfig

Linker Script

The first file specified in the SRCS variable above must be a "linker script" file. In fact, z88dk-z80asm works with SECTIONS, so you need a file that will organize them, place them. The sections that are strictly required, because used by the kernel are:

  • RST_VECTORS
  • SYSCALL_ROUTINES
  • SYSCALL_TABLE
  • KERNEL_TEXT
  • KERNEL_STRLIB
  • KERNEL_DRV_VECTORS (must contain the table of drivers)
  • KERNEL_BSS (must be in RAM!)

You can check the one for zeal8bit target here: https://github.com/Zeal8bit/Zeal-8-bit-OS/blob/main/target/zeal8bit/linker.asm

Drivers

After the linker script file, the files that you specified in unit.mk's SRCS variable, should be the drivers for your board.
Drivers must follow the pattern I explained in the README.md file.

I highly advise that the first driver you specify is your standard output, so the UART in your case. To register a driver as the standard output, call the routine zos_vfs_set_stdout with the driver address in HL. As such, every write to the standard output will be done through your UART, including the boot banner.
For more info, check zeal8bit's video.asm driver: https://github.com/Zeal8bit/Zeal-8-bit-OS/blob/main/target/zeal8bit/video.asm#L46

Similarly, one driver should register itself as the standard input, used when invoking read in the standard input.
The routine to call to register a driver as standard input is zos_vfs_set_stdin.
For more info, check zeal8bit's keyboard.asm driver: https://github.com/Zeal8bit/Zeal-8-bit-OS/blob/main/target/zeal8bit/keyboard.asm#L22

Storage

Do you have any storage on your board? CompactFlash? SDCard? Floppy disk?
Just like zeal8bit target, it is possible to use the ROM as a read-only disk. In that case, you will need to write a ROM driver that will register itself as a read-only disk (using romdisk filesystem). Check this file for this: https://github.com/Zeal8bit/Zeal-8-bit-OS/blob/main/target/zeal8bit/romdisk.asm#L15

More info

If you have any question or if you need some help to port the OS, feel free to contact me. You can also find me on Discord or QQ Group (661401085).

Zeal8bit commented

For more porting information, please check the Porting to another machine section of the README, or use the TRS-80 target as an example: https://github.com/Zeal8bit/Zeal-8-bit-OS/tree/main/target/trs80