microvm

README

TamaGo - bare metal Go - QEMU microvm support

tamago | https://github.com/usbarmory/tamago

Copyright (c) WithSecure Corporation

Authors

Andrea Barisani
andrea@inversepath.com

Andrej Rosano
andrej@inversepath.com

Introduction

TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal AMD64/ARM/RISC-V processors.

The microvm package provides support for QEMU microvm paravirtualized Kernel-based Virtual Machine (KVM) configured with a single AMD64 core.

Documentation

For more information about TamaGo see its repository and project wiki.

For the underlying driver support for this board see package amd64 and microvm.

The package API documentation can be found on pkg.go.dev.

Supported hardware

CPU	Board	CPU package	Board package
AMD/Intel 64-bit	QEMU microvm	amd64	qemu/microvm

Compiling

Go applications are simply required to import, the relevant board package to ensure that hardware initialization and runtime support take place:

import (
	_ "github.com/usbarmory/tamago/board/qemu/microvm"
)

Build the TamaGo compiler (or use the latest binary release):

wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
unzip latest.zip
cd tamago-go-latest/src && ./all.bash
cd ../bin && export TAMAGO=`pwd`/go

Go applications can be compiled as usual, using the compiler built in the previous step, but with the addition of the following flags/variables:

GOOS=tamago GOARCH=amd64 ${TAMAGO} build -ldflags "-T 0x10010000 -R 0x1000" main.go

An example application, targeting the QEMU microvm platform, is available.

Build tags

The following build tags allow application to override the package own definition of external functions required by the runtime:

• linkramsize: exclude ramSize from mem.go
• linkprintk: exclude printk from console.go

Executing and debugging

The example application provides reference usage and a Makefile target for automatic creation of an ELF image as well as paravirtualized execution.

QEMU

qemu-system-x86_64 \
	-machine microvm,x-option-roms=on,pit=off,pic=off,rtc=on \
	-global virtio-mmio.force-legacy=false \
	-enable-kvm -cpu host,invtsc=on,kvmclock=on -no-reboot \
	-m 4G -nographic -monitor none -serial stdio \
        -device virtio-net-device,netdev=net0 -netdev tap,id=net0,ifname=tap0,script=no,downscript=no \
	-kernel example

The paravirtualized target can be debugged with GDB by adding the -S -s flags to the previous execution command, this will make qemu waiting for a GDB connection that can be launched as follows:

gdb -ex "target remote 127.0.0.1:1234" example

Breakpoints can be set in the usual way:

b ecdsa.Verify
continue

License

tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation

These source files are distributed under the BSD-style license found in the LICENSE file.

The TamaGo logo is adapted from the Go gopher designed by Renee French and licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector illustration by Hugo Arganda.

Documentation

Overview

Package microvm provides hardware initialization, automatically on import, for the QEMU microvm machine configured with a single x86_64 core.

This package is only meant to be used with `GOOS=tamago GOARCH=amd64` as supported by the TamaGo framework for bare metal Go, see https://github.com/usbarmory/tamago.

Index

• Constants
• Variables
• func Init()

Constants

const (
	// Communication port
	COM1 = 0x3f8

	// Intel I/O Programmable Interrupt Controllers
	LAPIC_BASE   = 0xfee00000
	IOAPIC0_BASE = 0xfec00000
	IOAPIC1_BASE = 0xfec10000

	// VirtIO Memory-mapped I/O
	VIRTIO_MMIO_BASE = 0xfeb00000

	// VirtIO Networking
	VIRTIO_NET0_BASE = VIRTIO_MMIO_BASE + 0x2e00
	VIRTIO_NET0_IRQ  = 47
)

Peripheral registers

Variables

var (
	// AMD64 core
	AMD64 = &amd64.CPU{}

	// Local APIC
	LAPIC = &apic.LAPIC{
		Base: LAPIC_BASE,
	}

	// I/O APIC - GSI 0-23
	IOAPIC0 = &apic.IOAPIC{
		Index:   0,
		Base:    IOAPIC0_BASE,
		GSIBase: 0,
	}

	// I/O APIC - GSI 24-47
	IOAPIC1 = &apic.IOAPIC{
		Index:   1,
		Base:    IOAPIC1_BASE,
		GSIBase: 24,
	}

	// Real-Time Clock
	RTC = &rtc.RTC{}

	// Serial port
	UART0 = &uart.UART{
		Index: 1,
		Base:  COM1,
	}
)

Peripheral instances

Functions

func Init

func Init()

Init takes care of the lower level initialization triggered early in runtime setup.