github.com/jspc/eggos@v0.5.1-0.20221028160421-556c75c878a5/README.md (about) 1 <h1 align="center"> 2 <img src="./assets/files/eggos.png" /> 3 </h1> 4 5  6 7 [中文说明](README_CN.md) 8 9 A Go unikernel running on x86 bare metal 10 11 Run Go applications on x86 bare metal, written entirely in Go (only a small amount of C and some assembly), support most features of Go (like GC, goroutine) and standard libraries, also come with a network stack that can run most `net` based libraries. 12 13 The entire kernel is a go application running on ring0. There are no processes and process synchronization primitives, only goroutines and channels. There is no elf loader, but there is a Javascript interpreter that can run js script files, and a WASM interpreter will be added to run WASM files later. 14 15 # Background 16 17 Go's runtime provides some basic operating system abstractions. Goroutine corresponds to processes and channel corresponds to inter-process communication. In addition, go has its own virtual memory management, so the idea of running Go programs on bare metal was born. 18 19 It turns out that Go has the ability to manipulate hardware resources, thanks to Go's controllable memory layout, the ability to directly translate hardware instructions without a virtual machine, and C-like syntax. These all make it possible for Go to write programs that run on bare metal. 20 However, there are also some challenges. Go piling in many instructions to perform coroutine scheduling and memory GC, which brings some troubles in some places that cannot be reentrant, such as interrupt handling and system calls. 21 22 In general, writing kernel in Go is a very interesting experience. On the one hand, it gave me a deep understanding of Go's runtime. On the other hand, it also provided an attempt to write the operating system kernel on bare metal in addition to the C language. 23 24 # Architecture 25 26 <img src="https://i.imgur.com/gnq4m9h.png" width="700" /> 27 28 # Snapshot 29 30  31  32  33 34 35 36 # Feature list 37 38 - Basic Go features, such as GC, goroutine, channel. 39 - A simple console supports basic line editting. 40 - Network stack supports tcp/udp. 41 - Go style vfs abstraction using [afero](https://github.com/spf13/afero) 42 - A nes game emulator using [nes](https://github.com/fogleman/nes) 43 - A Javascript interpreter using [otto](https://github.com/robertkrimen/otto) 44 - VBE based frame buffer. 45 - Some simple network apps (httpd, sshd). 46 - GUI support by [nucular](https://github.com/aarzilli/nucular). 47 48 49 # Dependencies 50 51 - Go 1.16.x (higher versions may not work) 52 - gcc 53 - qemu 54 - mage 55 56 ## MacOS 57 58 ``` bash 59 $ go get github.com/magefile/mage 60 $ brew install x86_64-elf-binutils x86_64-elf-gcc x86_64-elf-gdb 61 $ brew install qemu 62 ``` 63 64 ## Ubuntu 65 66 ``` bash 67 $ go get github.com/magefile/mage 68 $ sudo apt-get install build-essential qemu 69 ``` 70 71 # Quickstart 72 73 ``` bash 74 $ mage qemu 75 ``` 76 77 # Build your own unikernel 78 79 eggos has the ability to convert normal go program into an `ELF unikernel` which can be running on bare metal. 80 81 First, get the `egg` binary, which can be accessed through https://github.com/icexin/eggos/releases, or directly through `go install github.com/icexin/eggos/cmd/egg` 82 83 Run `egg build -o kernel.elf` in your project directory to get the kernel file, and then run `egg run kernel.elf` to start the qemu virtual machine to run the kernel. 84 85 `egg pack -o eggos.iso -k kernel.elf` can pack the kernel into an iso file, and then you can use https://github.com/ventoy/Ventoy to run the iso file on a bare metal. 86 87 Here are some examples [examples](./app/examples) 88 89 Happy hacking! 90 91 # Debug 92 93 You can directly use the gdb command to debug, or use vscode for graphical debugging. 94 95 First you need to install gdb, if you are under macos, execute the following command 96 97 ``` bash 98 brew install x86_64-elf-gdb 99 ``` 100 101 Use the extension `Native Debug` in vscode to support debugging with gdb 102 103 First execute the `mage qemudebug` command to let qemu start the gdb server, and then use the debug function of vscode to start a debug session. The debug configuration file of vscode is built into the project. 104 105 Go provides simple support for gdb, see [Debugging Go Code with GDB](https://golang.org/doc/gdb) for details 106 107  108 109 # Running on bare metal 110 111 If you want eggos to run on bare metal, it is recommended to use grub as the bootloader. 112 113 The multiboot.elf generated after executing the make command is a kernel image conforming to the multiboot specification, which can be directly recognized by grub and booted on a bare metal. The sample configuration file refer to `boot/grub.cfg` 114 115 # Documentation 116 117 [docs/README.md](docs/README.md) 118 119 # Roadmap 120 121 - [ ] WASM runner 122 - [x] GUI support 123 - [x] 3D graphic 124 - [x] x86_64 support 125 - [ ] SMP support 126 - [ ] Cloud server support (virtio) 127 - [ ] Raspberry Pi support (arm64 aka aarch64) 128 129 # Bugs 130 131 The program still has a lot of bugs, often loses response or panic. If you are willing to contribute, please submit a PR, thank you! 132 133 # Special thanks 134 135 The birth of my little daughter brought a lot of joy to the family. This project was named after her name ` 136 Xiao Dandan`. My wife and mother also gave me a lot of support and let me work on this project in my spare time. :heart: :heart: :heart: