Exploring MSX-DOS and CP/M on OneChipBook FPGA-powered laptop

The OneChipBook, available on AliExpress for around $200, is a very interesting FPGA-powered laptop with 32MB RAM, a 10-inch 1024×768 LCD display and built-in stereo speakers. There are also PS2 ports, joystick ports, as well as VGA, composite and S-video output ports. With some efforts, this device can be programmed into an MSX2+ machine running MSX-DOS 2.31 with a total of 2MB of RAM:

MSX-DOS is just like MS-DOS with some quirks typical of early DOS versions. For example, CD\ is rejected but CD \ (with a space) is accepted. Interestingly, although the boot drive letter is A: for a floppy drive, the OS can access up to 2GB on the SD card, as long as the card is FAT16 formatted and is not SDHC.

Because the graphic resolution on the MSX2+ is only 256×212, text looks pixelated in 80×25 mode. For comparison, on a PC running MS-DOS, screen resolution is 640×400 in 80×25 VGA mode. As with MS-DOS, the delay at the end of DIR to count free space is very annoying. To avoid this, use LS.COM, which doesn’t display free space. However, LS.COM is slow to start and only displays file/folder names without dates or sizes.

Text editors

KID is a popular text file editor for the MSX. AKID.COM is the ASCII (English) version while KID.COM is the Japanese version. CONKID.COM allows you to make certain editor configurations.

The editor interface is very simple, with no menu displayed by default, allowing you to make full use of the 80×25 display for typing. To show the menu, press F1. To save a file, press S. To quit, press Q. The shortcut are the same on both the English and Japanese versions:

Another good editor is Milli 0.7, a Nano clone for the MSX. In this version of Nano, you must press Ctrl-Z to quit. Upon exit, the “COLOR/AUTO/GOTO/LIST/RUN” shortcut bar will remain at the bottom of the screen until a reboot, which is rather annoying.

To be able to run AKID.COM and MILLI.COM from any folder, I add the correct paths to AUTOEXEC.BAT, just like MS-DOS:

Tiny Binfile Editor or TBED is a very good hex editor for the MSX. The characters look quite big since 40×25 (and not 80×25) is used:

MSX-DOS also supports CP/M applications and WordStar (WS.COM) runs just fine. For the best display output, configure WS.COM to use Zenith as terminal. Sometimes, as text is typed or moved around, the user interface will be distorted. Perhaps some advanced console codes used by WordStar to update the screen are not fully understood by MSX-DOS. In the screen below, the ruler has been messed up:

BASIC interpreters

Without any bootable device, the laptop boots to ROM BASIC, typical of computers at the time:

MBASIC, a popular BASIC interpreter for CP/M, works fine too. To quit MBASIC, type SYSTEM. You can’t use SYSTEM on the ROM BASIC, which has no operating system to exit to.

On MSX-DOS v2, command COLOR will set the the console foreground and background color. Seeing a different color once in a while can be refreshing:

Turbo Pascal

To get Turbo Pascal 3.0 for CP/M 80 working on the OneChipBook, you must run TINST.COM and set the terminal to Zenith. This will result in no highlighting for keywords or shortcut keys (e.g. begin, end, or E for Edit), but the screen layout will be preserved. Selecting other terminals will result in garbled text output. It is worth noting that there are several different versions of TINST.COM on the Internet. On the MSX, some versions of TINST.COM will just exit, some others will attempt to switch to drive N: and result in an Invalid Drive error message (or BDOS Error On N: Select if executed on CP/M). You must find the correct version and choose Screen Installation to configure your terminal:

If the arrow key does not move in your Turbo Pascal editor, select Command Installation and remap these keys. To start editing a file, run TURBO.COM, press E for Edit and enter filename. Press Ctrl-K-D to exit the editor and press R to run. Fortunately, there was no screen corruption when using Turbo Pascal in Zenith mode and I was able to write a quick program to display numbers from 0 to 100 using the TP editor:

C compilers

Mix-C, a C compiler for CP/M, works fine too. Running CC.COM will compile the C source code (e.g. HELLO.C) into HELLO.MIX. To generate an executable COM file, use the linker (LINKER.COM). This is my test program compiled using MIX-C:

HELLO.MIX, the output of Mix-C compiler, is the equivalent of an object file (.O) in a modern compiler:

The presence of SCANF.C, STDLIB.C and other files with standard C function names in the MIX-C folder suggests that this compiler only understands a very limited subject of C. Perhaps unsurprisingly, STDLIB.H contains only declarations of jmp_buf  and REGS for Z80 registers. Modern compilers move jmp_buf to setjmp.h.

BD Software C Compiler is a lightweight C compiler for CP/M and works well on MSX-DOS. This is the output of my “Hello World” application, compiled with BDSC using COMPILE.BAT, which just calls CC.COM and CLINK.COM:

C80 v3.1 is another CP/M C compiler, released in 1984 by The Software Toolworks. Run C.COM to generate an assembly listing, and use AS.COM to generate the executable. AS.COM is a miniature assembler which was perhaps designed to only work with ASM files produced by C.COM. It is very picky on syntax and will complain on trivial things like space, tabs or line breaks. Do not use it on hand written assembly.

Other CP/M C compilers such as AZ 1.06D, Tiny C, Small C, or Hi-Tech C will work on the MSX. The official compiler by ASCII Corporation, MSX-C version 1.10 and 1.20, also works well, although compilation is a bit slow due to the complexity of the included libraries. For fast compilation, use C80 V3.1, or BDSC, unless you want to make use of MSX specific capabilities such as graphics or sound.

Assemblers

This is Z80ASM, a much more matured assembler released in 1983, compiling a Hello World program:

Z80ASM has its own quirks too. Although the source file must have .Z80 extension, you should pass this extension in the command line. For example, Z80ASM HELLO.Z80 will fail while Z80ASM HELLO will be accepted. This is the code for the above Hello World program:

org 100h
start: ld c,9
ld de,msg
call 5
ret
msg: db 'Hello World',13,10,'$'

You can’t do Ctrl-Alt-Del (as well as Page Up/Page Down) on this machine, so I wrote the following assembler program to reboot the machine without having to press the power button twice. Compile it with Z80ASM and just run REBOOT:

org 100h ; CP/M transient program load address (COM file entry)
di ; Disable interrupts
ld a,(0FCC1h) ; Load A with configuration byte from BIOS data area
ld h,00h ; Clear H
ld l,00h ; Clear L
rst 30h ; Reboot
db 0

The following program will start BASIC in ROM. Without this, you will have to remove the SD card and reboot the machine to enter ROM BASIC.

org 100h
di
ld a,(0fcc1h)
ld h,01h
ld l,50h
rst 30h
db 0

This is DEBUG.COM for MSX, which is similar to DEBUG.COM from MS-DOS. You can learn a lot about Z80 assembly just by using the built-in assembler:

Games

A computer wouldn’t be fun without at least some games. Other than cartridge games (more on that later), several CP/M text games will work just fine on MSX-DOS. Here is Zork, a famous 1980 text adventure series. After each scene, Zork will wait for you to tell it what to do next (open mailbox or read leaflet). Obviously, there is no AI involved (unlike ChatGPT), just some basic pattern matching:

This Hangman game works well, only after setting the terminal to Zenith Z19:

And finally, loading an MSX ROM file works too, using either ROMLOAD or EXECROM, depending on the ROM. I managed to run Arkanoid using EXECROM, after enabling DIP switch 4,5,6 to emulate a sound cartridge. Audio works fine too.

System utilities

This is M.COM, a file manager for the MSX. The characters look much sharper since M.COM works in graphic mode (and not text mode).

Unfortunately M.COM is only good for running programs and running predefined commands on the selected file. There are no built-in viewers, editors, or support for files manipulation, unlike Norton Commander. I didn’t use M.COM much during my test. If anything, MSX-DOS has built-in DOSKEY support, which is very convenient. MS-DOS did not have DOSKEY until version 5.

Several graphics file viewers exist for the MSX. For example, PNGView is able to load my sample PNG file:

I found a bitmap (.BMP) viewer, V9BMP, which kept complaining “V9990 not found”, regardless of the input file format, or whether the file exists:

MSX-DOS does not have a MEM command. To inspect memory configuration and perform RAM test, you can use TestRAM v1.0 instead. On my unit, the utility reported an MSX2+ with 64KB of base memory, 128KB of video RAM and a RAM size of 2048MB:

Video output

The composite video ports works, but only after mucking with DIP switches 1,2,3 to disable the built-in LCD and set the correct video mode. I am not sure why we cannot display video on both the built-in LCD and the composite port at the same time

The VGA port doesn’t work on my unit. Connecting any VGA cable (even without a display attached) will just turn the laptop off, requiring a power cycle (with a charger plugged in) to recover, as if the connected cable has created a short and confused the power circuitry. I tried toggling DIP switches 1,2,3 as well as Fn-1 with no luck. The PS2 keyboard port works, only if Fn+4 is pressed shortly after pressing the power button and while the MSX logo is still being displayed, which is useless for all intent and purposes.

There are 3 buttons (labelled F,V,T) in the middle of the two speakers. F toggles TURBO mode, V switches between different video modes (not all will be compatible with the LCD), while T just toggles the blue LED indicators. To test if TURBO mode is indeed working, run a DIR on a long directory or a C program to perform some calculations, and press F while the program is running. You should see that execution will be slower if TURBO is enabled, and faster if disabled.

File sharing

I tried hard to find a way to transfer files to this laptop without messing around with the SD card. The socket is very stiff and may be damaged after repeated removal, turning the laptop into an expensive paperweight. Studying the schematics, I realized there is a socket for an ESP-01S microcontroller, allowing me to add Wifi capabilities to the laptop. The ESP-01S can then be programmed to support UNAPI and files can be downloaded to the laptop using MSXHub. Unfortunately I have not been able to find a suitable firmware for the ESP-01S to make this work.

There is also a USB2.0 socket on the board which is not accessible from MSX-DOS without a suitable device driver. The two DB9 ports are for joysticks, but perhaps can be repurposed for data transfer. Or if I feel like it, I can write some simple C programs to output data by playing DTMF tones through the 3.5mm audio socket and decode it on my Windows machine. This will be the topic for another article.