MARSEMU

X11 virtual framebuffer with keyboard input for cross-debugging.

A project to emulate MARS's bitmap display and keyboard.

Tested under x86 and qemu-mips.

Quick start

git clone https://github.com/jimmy-zx/marsemu.git
cd marsemu
make
make examples
./build/server &  # or run in another terminal
./build/client_drawcorner

Dependencies

• gcc
• gcc-mips-linux-gnu
• libx11-dev
• libxext-dev

All of the dependencies can be installed via apt:

sudo apt install build-essential gcc-mips-linux-gnu libx11-dev libxext-dev

System Requirements

Host: x86

A X11 server with MIT-SHM support. (The server and client must run on the same host.)

Emulation:

• qemu-system-mips
• qemu-user

Debugging

• gdb-multiarch

Features

Server

• Virtual Framebuffer
• Keyboard

Client

• plot: draw pixels directly
• psf: draw letters using PSF fonts
• kbd: get keyboard input

Usage

Example usage using MIPS asm: client_drawcorner.s. Compilation instructions: Makefile

Calling conventions: follow System V MIPS ABI. This folder provides some examples and a macro to help you setup the stack frame.

Architecture

+----------+     +----------------+         +----------------------------+
| X Server | <-> | MARSEMU Server | <-SHM-> | QEMU-user                  |
+----------+     +----------------+         | +------------------------+ |
                                            | | MARSEMU Client Library | |
                                            | +------------------------+ |
                                            |            ||              |
                                            | +------------------------+ |
                                            | | Userspace MIPS Program | |
                                            | +------------------------+ |
                                            +----------------------------+

Notes

• ssh -X will not be supported (see here)

• Users using WSL: use WSLg instead

• Scaling is not natively supported. You can use run_scaled on X11 or magnify.exe on Windows.

Porting to MARS

• MARS does not support several derivatives used by GNU as. A simple preprocessor is provided to assess some of these.

Related Resources

Xlib

One tutorial, Another tutorial

Xlib MIT-SHM Extension

XShmXXXImage() call, Design choice

SHM

shmat() system call

PSF

PC Screen Font Specification, Guide from osdev.org