Since this project wasn’t about the actual functionality of the circuit but to get firm with the workflow, I limited the requirements pretty strict to keep focus on the goal:

Where to begin? I dumped my brain into a mind map. There are no bad ideas. In fact negative feedback or cancling train of thought can kill the flow. First comes extrapolation and then filtering based on our requirements.

I came up with a “slice of an audio mixer”: mono input, mono output, mute and attenuate. The circuit is simple, but the functionality is quite handy. All parts are already around like fader for attenuation and push buttons for the mute.

ChatGPT suggested me to put fader and mute in series, pull down both to ground and add at least one capacitor at the output to smooth out dc voltages.

Then fader and button got mounted onto a prototyping board and the circuit hooked up to my euroack.

It worked like a charm \0/

This is basically the direct outcome of the brainstorming from the previous section.

After finalizing the first circuit so quickly I thought about a second one. Originally I planned to do a dead simple passive multiple where all audio jacks are just connected to each other. Since there is no inner logic, all jacks can be used both as input and output.

Then I thought about muting each jack individually with a push button.

Making my first own PCB was way more easier than I thought. It felt similar to do a 3d printing project. You start with an idea, prototype and hold the final product in your hands. The feedback loop on the other hand is quite large due to the shipping time.

KiCad is quite handy when you know which parts can be skipped and are irrelevant to the process. Finding the right footprint can be pain. In my next project, I’d first choose the components either laying around or at the seller of your desire. Doing it the other way around and searching for a component matching the footprint adds more unnecessary complexity to the workflow.

• design more
• add more complex artworks with different colors/layers
• enhance existing/more revisions
• teach others to make their own

Emulate hardware using software to run operating systems just like on real hardware. An instance of an emulated system is called virtual machine, or VM for short. The real machine on which the virtualization takes place is called host, while the emulated system is called guest. Hypervisor is the software providing the virtual machine.

While emulation is about rebuilding hardware within software, paravirtualization is quite the opposite: pass the real hardware through to the guest.

This also accelerates the performance of a virtual machine a lot, while the translation layer is not necessary anymore.

The virtual machine is still isolated and the kernel grants it its own memory regions and virtual cpus.

The Kernel Virtual Machine API (KVM for short) provides a set of functions to create and operate on virtual machines. The API can be accessed via /dev/kvm using ioctl operations.

The main steps summarized:

1. open /dev/kvm and compare version
2. processing unit: create VM with vcpu
3. get run status struct
4. allocate memory region and load bootable image
5. initialize registers and segments
6. run VM and respond to guest requests (like IO or shutdown)
7. do 6. repeateadly until the guest wants to halt

Open the kvm device and check the ABI version, which needs to be 12 or higher:

package main

import (
	"fmt"
	"os"
	"syscall"
)

const (
	// latest stable abi version
	KVM_VERSION = 12
)

var (
	// linux/kvm.h
	KVMIO                      = uintptr(0xAE)
	KVM_GET_API_VERSION        = uintptr(_IO(KVMIO, 0x00)) // -> 0xAE00
)

func main() {
	fd, err := syscall.Open("/dev/kvm", os.O_RDWR, 0600)
	if err != nil {
		fmt.Println("open:", err)
		return
	}
	defer func() {
		if err := syscall.Close(fd); err != nil {
			fmt.Println("close:", err)
		}
	}()

	kvmVersion, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(fd), uintptr(KVM_GET_API_VERSION), uintptr(0))
	if errno != 0 {
		fmt.Println("ioctl:", errno)
		return
	}

	if kvmVersion == KVM_VERSION {
		fmt.Printf("kvm version %d supported\n", kvmVersion)
	} else {
		fmt.Printf("kvm version %d is too old, need %d or newer\n", kvmVersion, KVM_VERSION)
	}
}

Using the kvm reference, we can now create a VM followed by a vcpu:

package main

import (
	"fmt"
	"os"
	"syscall"
)

const (
	KVM_VERSION = 12
)

var (
	// linux/kvm.h
	KVMIO                      = uintptr(0xAE)
	KVM_GET_API_VERSION        = uintptr(_IO(KVMIO, 0x00)) // -> 0xAE00
	KVM_CREATE_VM              = uintptr(_IO(KVMIO, 0x01))
	KVM_CREATE_VCPU            = uintptr(_IO(KVMIO, 0x41))
)

func main() {
	kvm, err := syscall.Open("/dev/kvm", os.O_RDWR, 0600)
	if err != nil {
		fmt.Printf("can't open kvm device: %s\n", err)
		return
	}
	defer syscall.Close(kvm)

	// check for stable kvm abi, needs to be >=12
	kvmVersion, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), KVM_GET_API_VERSION, 0)
	if errno != 0 {
		fmt.Printf(
			"errror getting kvm api version %d\n",
			errno,
		)
		return
	}

	if kvmVersion != KVM_VERSION {
		fmt.Printf(
			"kvm version %d is too old, need %d or newer\n",
			kvmVersion,
			KVM_VERSION,
		)
		return
	}

	vm, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), KVM_CREATE_VM, 0)
	if errno != 0 {
		fmt.Printf(
			"errror creating vm %d\n",
			errno,
		)
		return
	}
	defer syscall.Close(int(vm))

	vcpu, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(vm), KVM_CREATE_VCPU, 0)
	if errno != 0 {
		fmt.Printf(
			"errror creating vcpu %d\n",
			errno,
		)
		return
	}
	defer syscall.Close(int(vm))

	fmt.Printf("kvm-fd=%d vm-fd=%d vcpu-fd=%d\n", kvm, vm, vcpu)
}

The status of the virtual machine is contained in the kvm_run struct. This is especially needed when the VM interrupts and requests the host to do something (like IO). Before running the VM, we need to map the struct into user-space:

package main

import (
  "fmt"
  "os"
  "syscall"
)

const (
  KVM_VERSION = 12
)

var (
  // linux/kvm.h
  KVMIO                      = uintptr(0xAE)
  KVM_GET_API_VERSION        = uintptr(_IO(KVMIO, 0x00)) // -> 0xAE00
  KVM_CREATE_VM              = uintptr(_IO(KVMIO, 0x01))
  KVM_GET_VCPU_MMAP_SIZE     = uintptr(_IO(KVMIO, 0x04))
  KVM_CREATE_VCPU            = uintptr(_IO(KVMIO, 0x41))
)
type kvm_run struct {
  _          [8]byte
  exitReason uint32
}

func main() {
  // open kvm and check version...
  // create vm, vcpu

 // map kvmrun into user-space memory
 kvmRunSize, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), c, 0)

 rawKvmRun, err := syscall.Mmap(
   int(vcpu),
   0,
   int(kvmRunSize),
   syscall.PROT_READ|syscall.PROT_WRITE,
   syscall.MAP_SHARED,
 )
 if err != nil {
   fmt.Printf("error mapping kvm run: %s\n", err)
   return
 }

 kvmRun := (*(*kvm_run)(unsafe.Pointer(&rawKvmRun[0])))
 fmt.Println(kvmRun.exitReason)
}

• altough the size of the run structure is pretty constant, we query it via KVM_GET_VCPU_MMAP_SIZE
• *(*goType)(unsafe.Pointer(&bytes[offset])): dirty hack to convert a byte buffer into a go type. The usual C stuff…
• verification: no error and program prints exit-reason 0

Next we allocate some memory for the guest. In this example we reserve 1Mib (or 100000 hex) and load the given image file into it:

package main

import (
  "fmt"
  "os"
  "syscall"
  "unsafe"
)

const (
  GUEST_MEMORY = 0x100000 // 1Mib
  KVM_VERSION  = 12
)

var (
  // linux/kvm.h
  // KVM_...
  KVM_SET_USER_MEMORY_REGION = uintptr(_IOW(KVMIO, 0x46, unsafe.Sizeof(KVMUserspaceMemoryRegion{})))
)

// kvm_run ...

// kvm_userspace_memory_region from linux/kvm.h
type KVMUserspaceMemoryRegion struct {
  Slot          uint32
  Flags         uint32
  GuestPhysAddr uint64
  MemorySize    uint64 /* bytes */
  UserspaceAddr uint64 /* start of the userspace allocated memory */
}

func main(){
        // expect image file as first argument
  if len(os.Args) != 2 {
    fmt.Printf("usage: %s <image>\n", os.Args[0])
    return
  }
  // open kvm and check version...
  // create vm, vcpu
  // map kvmrun into user-space memory

  // load first argument 
  image, err := os.ReadFile(os.Args[1])
  if err != nil {
    fmt.Printf("error loading image: %s\n", err)
    return
  }

  // allocate guest memory
  guestMemory, err := syscall.Mmap(
    -1, // ignored because of MAP_ANONYMOUS
    0,
    GUEST_MEMORY,
    syscall.PROT_READ|syscall.PROT_WRITE,
    syscall.MAP_ANONYMOUS|syscall.MAP_PRIVATE,
  )
  if err != nil {
    fmt.Printf("error allocating guest memory: %s\n", err)
    return
  }

  // copy embedded image
  copy(guestMemory, image)

  memoryRegion := &KVMUserspaceMemoryRegion{
    Slot:          0,
    Flags:         0,
    GuestPhysAddr: 0,
    MemorySize:    uint64(GUEST_MEMORY),
    UserspaceAddr: uint64(uintptr(unsafe.Pointer(&guestMemory[0]))),
  }
  _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vm), KVM_SET_USER_MEMORY_REGION, uintptr(unsafe.Pointer(memoryRegion)))
  if errno != 0 {
    fmt.Printf("error setting memory region: %d\n", err)
    return
  }
}

• KVMUserspaceMemoryRegion declares the relation between host and guest memory address space
• host memory starts at the pointer of the allocated memory
• guest starts at zero, which is the beginning of its address space, if we add multiple regions we could set this to an other value
• memory size is equal for both address spaces as this is a 1:1 mapping and refers to the size of the allocated memory
• KVM_SET_USER_MEMORY_REGION adds a memory region to the given VM
• verification: no error

Before we can run the VM, the registers and segments of our vcpu need to be set up properly. This comes along with a bunch of structs that need to be redefined within our go program. For completeness, I define every field although we don’t need many.

const (
  GUEST_MEMORY = 0x100000 // 1Mib
  KVM_VERSION  = 12

  // linux/kvm.h
  // ...
  KVM_GET_REGS               = uintptr(_IOR(KVMIO, 0x81, unsafe.Sizeof(KVMRegs{})))
  // not needed but for sake of completeness
  // KVM_SET_REGS               = uintptr(_IOW(KVMIO, 0x82, unsafe.Sizeof(KVMRegs{})))

  KVM_GET_SREGS              = uintptr(_IOR(KVMIO, 0x83, unsafe.Sizeof(KVMSRegs{})))
  KVM_SET_SREGS              = uintptr(_IOW(KVMIO, 0x84, unsafe.Sizeof(KVMSRegs{})))
)

// KVM Structs (asm/kvm.h)
type KVMRegs struct {
  RAX, RBX, RCX, RDX uint64
  RSI, RDI, RSP, RBP uint64
  R8, R9, R10, R11   uint64
  R12, R13, R14, R15 uint64
  RIP, RFlags        uint64
}

// needed for sregs
type KVMSegment struct {
  Base                           uint64
  Limit                          uint32
  Selector                       uint16
  Tyype                          uint8
  Present, DPL, DB, S, L, G, AVL uint8
  Unusable                       uint8
  _                              uint8 // padding
}

// needed for sregs
type KVMDTable struct {
  Base  uint64
  Limit uint16
  _     [3]uint16 //padding
}

type KVMSRegs struct {
  CS, DS, ES, FS, GS, SS  KVMSegment
  TR, LDT                 KVMSegment
  GDT, IDT                KVMDTable
  CR0, CR2, CR3, CR4, CR8 uint64
  Efer                    uint64
  ApicBase                uint64
  InterruptBitmap         [(256 + 63) / 64]uint64
}

func main(){
  registers := KVMRegs{
    RIP: 0,
    RFlags: 0x2,
  }
  _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_SET_REGS, uintptr(unsafe.Pointer(&registers)))
  if errno != 0 {
    fmt.Printf("KVM_SET_REGS: %s\n", errno)
    return
  }

  // get initial state of regs
  var sregs KVMSRegs
  _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_GET_SREGS, uintptr(unsafe.Pointer(&sregs)))
  if errno != 0 {
    fmt.Printf("KVM_GET_SREGS: %s\n", errno)
    return
  }

  sregs.CS.Base = 0
  sregs.CS.Selector = 0

  _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_SET_SREGS, uintptr(unsafe.Pointer(&sregs)))
  if errno != 0 {
    fmt.Printf("KVM_SET_REGS: %s\n", errno)
    return
  }
}

var smallestBootloader = []byte{0xf4}

It’s time to run our VM!

const (
  // ...
  KVM_RUN                    = uintptr(_IO(KVMIO, 0x80))
  // ...
)

func main(){
    // ...
    _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_RUN, 0)
    if errno != 0 {
      fmt.Printf("KVM_RUN: %s\n", errno)
      return
    }

    fmt.Println(kvmRun.exitReason)
}

5 is the output we yearn for. It’s the halt exit-reason.

Congratulations! You just ran your first VM \o/

Now we take a look how guest and host communicate with each other. The KVM_RUN command not only returns when the VM halted. There are a bunch of other reasons, most notably KVM_EXIT_REASON_IO.

Every time the VM wants to access real hardware, KVM_RUN returns and we need to provide it. This is where device emulation comes into play like a serial uart console, vga, a real time clock or network interface.

The halt program was basic enough so we could just hardcode it with opcodes. In order to be flexible and write more sophisticated bootloader, we will code all upcoming examples with assembler.

Let’s spice it up and print something the guest sent to us.

Luckily, we control both ends: hypervisor and guest. This makes communication a lot easier. Roll the dice and choose a port of your desire. I go with 0x42:

mov al, "#"   ; set accumulator to the character we wanna print
mov dx, 0x42  ; set data register to the desired port
out dx, al    ; let's print
hlt           ; halt and exit guest

Now we run KVM_RUN in a loop and check the exit reason. On halt we do the usual exit and on IO we print the guests data:

const (
  /...
  KVM_EXIT_REASON_HALT = 5
  KVM_EXIT_REASON_IO   = 2

  KVM_IO_IN  = 0
  KVM_IO_OUT = 1
)

type KVMRun struct {
  _          [8]byte
  exitReason uint32
  _          [20]byte
  details    [256]byte
}

type KVMExitIO struct {
  Direction  uint8
  Size       uint8
  Port       uint16
  Count      uint32
  DataOffset uint64
}

main(){
  // ...
  for {
    _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_RUN, 0)
    if errno != 0 {
      fmt.Printf("KVM_RUN: %s\n", errno)
      return
    }
    fmt.Printf("exit-reason=%d\n", kvmRun.exitReason)

  for {
    _, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_RUN, 0)
    if errno != 0 {
      fmt.Printf("KVM_RUN: %s\n", errno)
      return
    }
    switch kvmRun.exitReason {
    case 0:
      fmt.Println("sometimes things get complicated")
      return
    case KVM_EXIT_REASON_HALT:
      return
    case KVM_EXIT_REASON_IO:
      ioDetails := (*KVMExitIO)(unsafe.Pointer(&kvmRun.details))
      start := *(*[]byte)(unsafe.Pointer(&kvmRun))
      if ioDetails.Direction == KVM_IO_OUT && ioDetails.Port == 0x42 {
        fmt.Println(string(start[ioDetails.DataOffset]))
      }
    default:
      fmt.Println("unhandeled exit reason", kvmRun.exitReason)
    }
  }
}

• code 2 indicate an io request from the guest
• extend the KVMRun struct with details containing details about the requested io operation
  • direction: indicates if it’s an input 0 or output 1 operation
  • size: buffersize to read/write
  • port: each hardware component has it’s own port
  • count: ??
  • data offset: offset starting from the kvm_run struct address to the actual data

• basic driver: serial console, realtime clock
• single-step debugger
• support more exit reasons

We’ve built a hypervisor!

It’s far from usable in production, but it is real. It’s a starting point to add further devices, exit-codes and other functionality.

I was surprised about the straight-forward steps to initialize and run my first VM with kvm. The register and segment initialization such as the go unsafe pointer stuff is a bit counter-intuitive for gophers, but necessary to make use of KVM. The kvm-run mechanism which return for every host invocation with an exit reason is quite clever and clear.

Consolidating all the snippets can be anyoing since they might diverge as I rewrote the programs as I wrote this blog post. The following standalone program boots any given image and writes io requests from port 0x42 to the screen.

package main

import (
	"fmt"
	"os"
	"syscall"
	"unsafe"
)

const (
	GUEST_MEMORY = 0x100000 // 1Mib
	KVM_VERSION  = 12

	// linux/kvm.h
	KVM_BASE                   = 0xAE00
	KVM_GET_API_VERSION        = KVM_BASE + 0x00
	KVM_CREATE_VM              = KVM_BASE + 0x01
	KVM_GET_VCPU_MMAP_SIZE     = KVM_BASE + 0x04
	KVM_CREATE_VCPU            = KVM_BASE + 0x41
	KVM_RUN                    = KVM_BASE + 0x80
	KVM_SET_USER_MEMORY_REGION = 0x4020ae46
	KVM_SET_REGS               = 0x4090ae82
	KVM_GET_SREGS              = 0x8138ae83
	KVM_SET_SREGS              = 0x4138ae84

	KVM_EXIT_REASON_HALT = 5
	KVM_EXIT_REASON_IO   = 2

	KVM_IO_IN  = 0
	KVM_IO_OUT = 1
)

// start of kvm_run from linux/kvm.h
type KVMRun struct {
	_          [8]byte
	exitReason uint32
	_          [20]byte
	details    [256]byte
}

type KVMExitIO struct {
	Direction  uint8
	Size       uint8
	Port       uint16
	Count      uint32
	DataOffset uint64
}

// kvm_userspace_memory_region from linux/kvm.h
type KVMUserspaceMemoryRegion struct {
	Slot          uint32
	Flags         uint32
	GuestPhysAddr uint64
	MemorySize    uint64 /* bytes */
	UserspaceAddr uint64 /* start of the userspace allocated memory */
}

// KVM Structs (asm/kvm.h)
type KVMRegs struct {
	RAX, RBX, RCX, RDX uint64
	RSI, RDI, RSP, RBP uint64
	R8, R9, R10, R11   uint64
	R12, R13, R14, R15 uint64
	RIP, RFlags        uint64
}

// needed for sregs
type KVMSegment struct {
	Base                           uint64
	Limit                          uint32
	Selector                       uint16
	Tyype                          uint8
	Present, DPL, DB, S, L, G, AVL uint8
	Unusable                       uint8
	_                              uint8 // padding
}

// needed for sregs
type KVMDTable struct {
	Base  uint64
	Limit uint16
	_     [3]uint16 //padding
}

type KVMSRegs struct {
	CS, DS, ES, FS, GS, SS  KVMSegment
	TR, LDT                 KVMSegment
	GDT, IDT                KVMDTable
	CR0, CR2, CR3, CR4, CR8 uint64
	Efer                    uint64
	ApicBase                uint64
	InterruptBitmap         [(256 + 63) / 64]uint64
}

func main() {
	if len(os.Args) != 2 {
		fmt.Printf("usage: %s <image>\n", os.Args[0])
		return
	}

	kvm, err := syscall.Open("/dev/kvm", os.O_RDWR, 0600)
	if err != nil {
		fmt.Printf("can't open kvm device: %s\n", err)
		return
	}
	defer syscall.Close(kvm)

	// check for stable kvm abi, needs to be >=12
	kvmVersion, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), KVM_GET_API_VERSION, 0)
	if errno != 0 {
		fmt.Printf(
			"errror getting kvm api version %d\n",
			errno,
		)
		return
	}

	if kvmVersion != KVM_VERSION {
		fmt.Printf(
			"kvm version %d is too old, need %d or newer\n",
			kvmVersion,
			KVM_VERSION,
		)
		return
	}

	vm, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), KVM_CREATE_VM, 0)
	if errno != 0 {
		fmt.Printf(
			"errror creating vm %d\n",
			errno,
		)
		return
	}
	defer syscall.Close(int(vm))

	vcpu, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(vm), KVM_CREATE_VCPU, 0)
	if errno != 0 {
		fmt.Printf(
			"errror creating vcpu %d\n",
			errno,
		)
		return
	}
	defer syscall.Close(int(vm))

	fmt.Printf("kvm-fd=%d vm-fd=%d vcpu-fd=%d\n", kvm, vm, vcpu)

	// map kvmrun into user-space memory
	kvmRunSize, _, errno := syscall.Syscall(syscall.SYS_IOCTL, uintptr(kvm), KVM_GET_VCPU_MMAP_SIZE, 0)
	if errno != 0 {
		fmt.Printf(
			"errror getting kvm_run size %d\n",
			errno,
		)
		return
	}
	fmt.Printf("kvm_run size: %d\n", kvmRunSize)

	rawKvmRun, err := syscall.Mmap(
		int(vcpu),
		0,
		int(kvmRunSize),
		syscall.PROT_READ|syscall.PROT_WRITE,
		syscall.MAP_SHARED,
	)
	if err != nil {
		fmt.Printf("error mapping kvm run: %s\n", err)
		return
	}

	kvmRun := /* skip *, we want a pointer! */ (*KVMRun)(unsafe.Pointer(&rawKvmRun[0]))

	// read image
	image, err := os.ReadFile(os.Args[1])
	if err != nil {
		fmt.Printf("error loading image: %s\n", err)
		return
	}

	// allocate guest memory
	guestMemory, err := syscall.Mmap(
		-1, // ignored because of MAP_ANONYMOUS
		0,
		GUEST_MEMORY,
		syscall.PROT_READ|syscall.PROT_WRITE,
		syscall.MAP_ANONYMOUS|syscall.MAP_PRIVATE,
	)
	if err != nil {
		fmt.Printf("error allocating guest memory: %s\n", err)
		return
	}

	fmt.Printf("image: %x\n", image)
	// copy embeded image
	copy(guestMemory, image)

	memoryRegion := &KVMUserspaceMemoryRegion{
		Slot:          0,
		Flags:         0,
		GuestPhysAddr: 0,
		MemorySize:    uint64(GUEST_MEMORY),
		UserspaceAddr: uint64(uintptr(unsafe.Pointer(&guestMemory[0]))),
	}
	_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vm), KVM_SET_USER_MEMORY_REGION, uintptr(unsafe.Pointer(memoryRegion)))
	if errno != 0 {
		fmt.Printf("error setting memory region: %s\n", errno)
		return
	}

	registers := KVMRegs{
		RIP:    0,
		RFlags: 0x2,
	}
	_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_SET_REGS, uintptr(unsafe.Pointer(&registers)))
	if errno != 0 {
		fmt.Printf("KVM_SET_REGS: %s\n", errno)
		return
	}

	// get initial state of regs
	var sregs KVMSRegs
	_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_GET_SREGS, uintptr(unsafe.Pointer(&sregs)))
	if errno != 0 {
		fmt.Printf("KVM_GET_SREGS: %s\n", errno)
		return
	}

	sregs.CS.Base = 0
	sregs.CS.Selector = 0

	_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_SET_SREGS, uintptr(unsafe.Pointer(&sregs)))
	if errno != 0 {
		fmt.Printf("KVM_SET_REGS: %s\n", errno)
		return
	}

	for {
		_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, uintptr(vcpu), KVM_RUN, 0)
		if errno != 0 {
			fmt.Printf("KVM_RUN: %s\n", errno)
			return
		}
		switch kvmRun.exitReason {
		case 0:
			fmt.Println("sometimes things get complicated")
			return
		case KVM_EXIT_REASON_HALT:
			return
		case KVM_EXIT_REASON_IO:
			ioDetails := (*KVMExitIO)(unsafe.Pointer(&kvmRun.details))
			start := *(*[]byte)(unsafe.Pointer(&kvmRun))
			if ioDetails.Direction == KVM_IO_OUT && ioDetails.Port == 0x42 {
				fmt.Println(string(start[ioDetails.DataOffset]))
			}
		default:
			fmt.Println("unhandeled exit reason", kvmRun.exitReason)
		}
	}
}

The ioctl logic to define a kvm command is a bit hard to read. I just ported it to go without reason about it much:

package main

const (
	_IOC_NRBITS   = uintptr(8)
	_IOC_TYPEBITS = uintptr(8)
	_IOC_SIZEBITS = uintptr(14)
	_IOC_DIRBITS  = uintptr(2)

	_IOC_NRMASK   = ((1 << _IOC_NRBITS) - 1)
	_IOC_TYPEMASK = ((1 << _IOC_TYPEBITS) - 1)
	_IOC_SIZEMASK = ((1 << _IOC_SIZEBITS) - 1)
	_IOC_DIRMASK  = ((1 << _IOC_DIRBITS) - 1)

	_IOC_NRSHIFT   = uintptr(0)
	_IOC_TYPESHIFT = (_IOC_NRSHIFT + _IOC_NRBITS)
	_IOC_SIZESHIFT = (_IOC_TYPESHIFT + _IOC_TYPEBITS)
	_IOC_DIRSHIFT  = (_IOC_SIZESHIFT + _IOC_SIZEBITS)

	_IOC_NONE  = uintptr(0)
	_IOC_WRITE = uintptr(1)
	_IOC_READ  = uintptr(2)
)

func _IOC(dir, tyype, nr, size uintptr) uintptr {
	return (((dir) << _IOC_DIRSHIFT) |
		((tyype) << _IOC_TYPESHIFT) |
		((nr) << _IOC_NRSHIFT) |
		((size) << _IOC_SIZESHIFT))
}

func _IO(tyype, nr uintptr) uintptr {
	return _IOC(_IOC_NONE, (tyype), (nr), 0)
}
func _IOR(tyype, nr, size uintptr) uintptr {
	return _IOC(_IOC_READ, (tyype), (nr), size)
}
func _IOW(tyype, nr, size uintptr) uintptr {
	return _IOC(_IOC_WRITE, (tyype), (nr), size)
}
func _IOWR(tyype, nr, size uintptr) uintptr {
	return _IOC(_IOC_READ|_IOC_WRITE, (tyype), (nr), size)
}

func _IOC_DIR(nr uintptr) uintptr {
	return (((nr) >> _IOC_DIRSHIFT) & _IOC_DIRMASK)
}
func _IOC_TYPE(nr uintptr) uintptr {
	return (((nr) >> _IOC_TYPESHIFT) & _IOC_TYPEMASK)
}
func _IOC_NR(nr uintptr) uintptr {
	return (((nr) >> _IOC_NRSHIFT) & _IOC_NRMASK)
}
func _IOC_SIZE(nr uintptr) uintptr {
	return (((nr) >> _IOC_SIZESHIFT) & _IOC_SIZEMASK)
}

func IOC_IN() uintptr {
	return (_IOC_WRITE << _IOC_DIRSHIFT)
}
func IOC_OUT() uintptr {
	return (_IOC_READ << _IOC_DIRSHIFT)
}
func IOC_INOUT() uintptr {
	return ((_IOC_WRITE | _IOC_READ) << _IOC_DIRSHIFT)
}
func IOCSIZE_MASK() uintptr {
	return (_IOC_SIZEMASK << _IOC_SIZESHIFT)
}
func IOCSIZE_SHIFT() uintptr {
	return (_IOC_SIZESHIFT)
}

Ever wondered how a json parser, regex, openssl, a webserver and whatsoever worked? Implement it and learn its functionality as you go.

Saw this new concept on hacker news or your new favorite O’Reilly book and want to test it? Well, then use what’s already there and reimplement it with the new concept. Both solutions can then be compared with each other. If they fulfill the same specification, the tests might even be usable for benchmarking.

Although the specification among several projects is equal and they can be used as drop-ins, their implementation differences can be worth weighting the pros and cons over another. Different languages, paradigms (OOP, functional, logical) or optimizations (SIMD, OpenCL/Cuda, …) can lead to significant performance differences.

Working on a problem that has already been solved makes it easier to shift the focus away from what-to-implement to how-to-implement. It’s not “Do I do the right thing?” but “Do I do the thing right?”. The difference may seem subtle, but at least for me, having a known-to-work specification helps me focus on progressing.

Of course there are also some arguments against it.

While it’s educational and fun to create something new, once it’s used in production by yourself or others, maintenance should be considered every now and then, which can get time consuming.

Building something from scratch often comes with a bunch of surrounding code that needs to be implemented before coming to the relevant core.

There are a few projects I want to do sometime in the future:

I have a quite respectable collection of synthesizer and eurorack modules to discover sound engineering on a basic level. Not only does the cathode tube screen looks pretty cool with its retro look, it also helps to investigate sound design and its issues.

Some wild eurorack appears.

Well, and I also want to hook it up on other random stuff. Like my DAW or some circuitry.

Testing the oscilloscope like software came intuitively in my mind when I was about to involve my little brother in testing. Rather than just quickly plug it in and play around, I thought it would be educational if I specify my testing strategy, step by step.

Dials and switches can get worn out over time, especially after 40 years. Based on the article description of the oscilloscope, the seller was closing a workshop and liquidated some equipment. So it might have been in heavy use.

• Test 4 - calibration signal:
  • given: turned on device
  • when: calibration pin gets connected to channel one
  • then: a noticeable change on the screen should’ve happened
• Test 5 - scaling:
  • given: channel one is connected to one of the calibration pins
  • when: the time-division and volts-division knobs get turned
  • then: the visualization on the screen should adjust accordingly
• Test 6 - offset:
  • when: x-offset and y-offset gets turned
  • then: the visualized signal should move accordingly on the screen

Screenshot of the 0.2V calibration signal

Repeat the process for channel two.

Although the oscilloscope is 40 years old, it works perfectly well for its condition and my needs. It passed all the tests. Some buttons get stuck when pressed, but can be freed by gently pulling them with pliers. I had expected some capacitors to be blown after such a long time. Maybe some are blown as I didn’t verify whether the visualized and actual voltage matched, but that’s not interesting for me.

A closer look to the oscilloscope’s interface.

The software testing approach for verifying this old piece of hardware worked surprisingly well. The test concept made formulating test scenarios straightforward. I could have simply plugged in the device and played around but taking a step back and formulating premises and their expected outcomes made the discovery of this analog technology even more fun.

The look and feel, such as the 1:1 control to function mapping inspired me to think more about symbiosis between analog and digital UI/UX principles.

• lots of levels
• visited eu parlament
• belgian waffles were super delicious

+rv=tch1b0

Error handling is extremely important for writing reliable and maintainable code. Once I started over with C, checking errno as often as possible saved me a load of time debugging.

On the other hand, error handling is time consuming when assumptions can be made. Like converting the aoc input consisting only of numbers.

In Golang, errors get returned and need to be handled explicitly. They can be ignored via “_” in an assignment, but by default it can’t be left on chaining functions like this:

func AnswerOfLife(a int) (int, error){
  if a == 42{
    return 42, nil
  }  
  return -1, errors.New("The answer to the ultimate question of life, the universe, and everything not found")
}

func main(){
  fmt.Println(AnswerOfLife(42) + AnswerOfLife(1337))
}

This doesn’t work, as AnswerOfLife has multiple return values: multiple-value AnswerOfLife(42) (value of type (int, error)) in single-value context.

You only life once is my answer to this problem:

func Yolo[T any](value T, _ error) T {
	return value
}

It takes the result of a function with two return values and drops the error.

This doesn’t come without a prize. Our code compiles but due to the missing error handling, the result may be confusing. Our program now compiles and outputs 41.

This is really bad for debugging. Therefore I created some variants that handle the error differently, depending on the situation:

func YoloBoom[T any](value T, err error) T {
	if err != nil {
		panic(err.Error())
	}
	return value
}

func YoloDefault[T any](value T, err error) T {
	if err == nil {
		return value
	}
	var def T
	return def
}

The first panics on error right away for situations where errors are unlikely. The second returns the default value of the value’s type. The later is useful when erroneous function calls should not be considered in an addition as YoloDefault would just return zero.

• Must
• Tja: German word for “oh well”
• OrPanic
• Require