drivers/{multiboot,vbe,qemu}: add docs (#102)

* drivers/vbe: add docs

Also, remove unused bootloaderMagic constant. A corresponding constant
is defined in and used by the multiboot package.

* drivers/qemu: add docs

* drivers/multiboot: fix typo; s/DrivesrAddr/DriversAddr/

* all: add go:build comments for Go build tags, as used by Go 1.17

ref: https://go.dev/doc/go1.17#build-lines

This commit was automated using goimports:

	find . -type f -name '*.go' | xargs -I '{}' goimports -w '{}'

app/cmd/nes.go

@@ -1,3 +1,4 @@
+//go:build nes
 // +build nes
 
 package cmd

app/cmd/win.go

@@ -1,3 +1,4 @@
+//go:build nk
 // +build nk
 
 package cmd

app/gin/server.go

@@ -1,3 +1,4 @@
+//go:build gin
 // +build gin
 
 package ginserver

app/httpd/prometheus.go

@@ -1,4 +1,6 @@
+//go:build prometheus
 // +build prometheus
+
 package httpd
 
 import (

app/phy/game.go

@@ -1,3 +1,4 @@
+//go:build phy
 // +build phy
 
 package phy

app/sshd/sshd.go

@@ -1,3 +1,4 @@
+//go:build sshd
 // +build sshd
 
 package sshd

drivers/multiboot/info.go

@@ -53,7 +53,7 @@ type Info struct {
 	MmapAddr   uint32
 
 	DriversLength uint32
-	DrivesrAddr   uint32
+	DriversAddr   uint32
 
 	ConfigTable uint32
 

drivers/qemu/qemu.go

@@ -1,11 +1,15 @@
+// Package qemu provides utility functions for interacting with the Qemu machine
+// emulator and virtualizer.
 package qemu
 
 import "github.com/icexin/eggos/kernel/sys"
 
 const (
+	// port used for Qemu exit commands.
 	qemuExitPort = 0x501
 )
 
+// Exit sends an exit command to Qemu with the given exit code.
 func Exit(code int) {
 	sys.Outb(qemuExitPort, byte(code))
 }

drivers/vbe/fb.go

@@ -9,24 +9,36 @@ import (
 	"github.com/icexin/eggos/kernel/mm"
 )
 
-const bootloaderMagic = 0x2BADB002
-
+// framebufferInfo specifies the dimensions and DMA address of the VBE
+// framebuffer.
 type framebufferInfo struct {
-	Addr   uint64
-	Pitch  uint32
-	Width  uint32
+	// DMA address of the VBE framebuffer.
+	Addr uint64
+	// Pitch is the stride (in bytes) between vertically adjacent pixels.
+	Pitch uint32
+	// Width of frame buffer in pixels.
+	Width uint32
+	// Height of frame buffer in pixels.
 	Height uint32
 }
 
 var (
-	info   framebufferInfo
+	// info specifies VBE framebuffer information.
+	info framebufferInfo
+	// buffer is an RGBA-buffer with the same pixel format and dimensions as
+	// fbbuf, used for double-buffering during rendering.
 	buffer []uint8
-	fbbuf  []uint8
+	// fbbuf provides direct memory access to the VBE framebuffer.
+	fbbuf []uint8
 
+	// DefaultView is the default view used for rendering.
 	DefaultView *View
+	// currentView is the current view used for rendering.
 	currentView *View
 )
 
+// bufcopy copies pixel data within the given rectangle from src to dst, based
+// on the given stride and copy operation.
 func bufcopy(dst, src []uint8, stride int, rect image.Rectangle, op func([]uint8, []uint8)) {
 	miny := rect.Min.Y
 	maxy := rect.Max.Y
@@ -39,23 +51,28 @@ func bufcopy(dst, src []uint8, stride int, rect image.Rectangle, op func([]uint8
 	}
 }
 
+// SaveCurrView returns the current view.
 func SaveCurrView() *View {
 	return currentView
 }
 
+// SetCurrView sets the current view, commiting pixel data to the framebuffer.
 func SetCurrView(v *View) {
 	currentView = v
 	v.Commit()
 }
 
+// IsEnable reports whether the VBE framebuffer has been initialized.
 func IsEnable() bool {
 	return fbbuf != nil
 }
 
+// Init initializes the VBE framebuffer based on the info data provided by
+// multiboot.
 func Init() {
 	bootInfo := &multiboot.BootInfo
 	if bootInfo.Flags&multiboot.FlagInfoVideoInfo == 0 {
-		uart.WriteString("[video] can't found video info from bootloader, video disabled\n")
+		uart.WriteString("[video] can't find video info from bootloader, video disabled\n")
 		return
 	}
 	if bootInfo.FramebufferType != 1 {

drivers/vbe/view.go

@@ -1,3 +1,4 @@
+// Package vbe provides access to the VESA VBE framebuffer.
 package vbe
 
 import (
@@ -5,26 +6,35 @@ import (
 	"image/draw"
 )
 
+// View provides a canvas for offscreen rendering which may be commited to the
+// framebuffer.
 type View struct {
+	// underlying offscreen rendering buffer.
 	buffer *image.RGBA
 }
 
+// NewView returns a new view for offscreen rendering which may be commited to
+// the framebuffer.
 func NewView() *View {
 	return &View{
 		buffer: image.NewRGBA(image.Rect(0, 0, int(info.Width), int(info.Height))),
 	}
 }
 
+// Canvas returns a canvas for rendering into the given view.
 func (v *View) Canvas() draw.Image {
 	return v.buffer
 }
 
+// Clear clears the given view, setting every pixel to black colour.
 func (v *View) Clear() {
 	for i := range v.buffer.Pix {
 		v.buffer.Pix[i] = 0
 	}
 }
 
+// CommitRect commits the given rectangle of the view to the framebuffer,
+// copying the pixels of the view within rect to the framebuffer.
 func (v *View) CommitRect(rect image.Rectangle) {
 	if fbbuf == nil {
 		return
@@ -52,6 +62,8 @@ func (v *View) CommitRect(rect image.Rectangle) {
 	})
 }
 
+// Commit commits the view to the framebuffer, copying every pixel of the view
+// to the framebuffer.
 func (v *View) Commit() {
 	if fbbuf == nil {
 		return

kernel/genvector.go

@@ -1,3 +1,4 @@
+//go:build ignore
 // +build ignore
 
 package main

magefile.go

@@ -1,4 +1,5 @@
-//+build mage
+//go:build mage
+// +build mage
 
 package main