From 2549dc983766d9a9f3e92a27587bc489f96a3fe8 Mon Sep 17 00:00:00 2001 From: Achilleas Anagnostopoulos Date: Tue, 8 Aug 2017 22:56:58 +0100 Subject: [PATCH 1/3] Add contributing and status markdown files --- CONTRIBUTING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++ STATUS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 STATUS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..45a1ff5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing Guide + +## Getting Started + +- Make sure you have a [GitHub Account](https://github.com/signup/free). +- Make sure you have [Git](http://git-scm.com/) installed on your system. +- [Fork](https://help.github.com/articles/fork-a-repo) the [repository](https://github.com/achilleasa/gopher-os) on GitHub. + +## Making Changes + + - [Create a branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository) for your changes. + - [Commit your code](http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository) for each logical change (see [tips for creating better commit messages](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message)). + - [Push your change](https://help.github.com/articles/pushing-to-a-remote) to your fork. + - [Create a Pull Request](https://help.github.com/articles/creating-a-pull-request) on GitHub for your change. + +The PR description should be as detailed as possible. This makes reviewing +much easier while at the same time serves as additional documentation that can +be referenced by future commits/PRs. + +This project treats the root folder of the repository as a Go [workspace](https://golang.org/doc/code.html#Workspaces). This +approach has several benefits: +- it keeps import paths short (no github.com/... prefix) +- it makes forking and merging easier +- it simplifies debugging (more compact symbol names) + +To develop for gopher-os you need to tweak your GOPATH so that the repository +folder is listed before any other GOPATH entry. This allows tools like +`goimports` to figure out the correct (short) import path for any gopher-os +package that your code imports. A simple way to do this would be by running the +following command: ```export GOPATH=`pwd`:$GOPATH```. + +## Unit tests and code linting + +Before submitting a PR make sure: +- that your code passes all lint checks: `make lint` +- you provide the appropriate unit-tests to ensure that the coverage does not + drop below the existing value (currently 100%). Otherwise, when you submit the + PR, the CI builder ([circle-ci](https://circleci.com)) will flag the build as + broken. + +Reaching 100% coverage is quite hard and requires the code to be designed with +testability in mind. This can get quite tricky if the code you are testing +relies on code that cannot be executed while running the tests. For example, if +the code you are currently working on needs to map some pages to virtual memory +then any call to the vmm package from your test code will cause the `go test` +to segfault. + +In cases like this, you need to design the code so calls to such packages can +be easily mocked while testing. If you are looking for inspiration here are +some examples that follow this approach: +- [bitmap allocator tests](https://github.com/achilleasa/gopher-os/blob/d804b17ed8651705f098d01bda65d8f0ded2c88e/src/gopheros/kernel/mem/pmm/allocator/bitmap_allocator_test.go#L15) +- [text console driver tests](https://github.com/achilleasa/gopher-os/blob/4b25971cef4bfd01877e3b5e948ee07a8f219608/src/gopheros/device/video/console/vga_text_test.go#L276) diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 0000000..bbc58e2 --- /dev/null +++ b/STATUS.md @@ -0,0 +1,58 @@ +## Current project status + +Here is the list of features currently working as well as some of the next +steps in the project roadmap. + +#### Core kernel features +- Bootloader-related + - [x] Multboot structure parsing (boot cmdline, memory maps, framebuffer and kernel image details) +- CPU + - [x] CPUID wrapper + - [x] Port R/W abstraction +- Memory management + - [x] Physical frame allocators (bootmem-based, bitmap allocator) + - [x] VMM system (page table management, virtual address space reservations, page RW/NX bits, page walk/translation helpers and copy-on-write pages) +- Exception handling + - [x] Page fault handling (also used to implement CoW) + - [x] GPF handling +- Hardware detection/abstraction layer + - [x] Multiboot-based HW detection + - [ ] ACPI-based HW detection + +#### Supported Go language features: +- [x] Go allocator +- [x] Maps +- [x] Interfaces +- [x] Package init() functions +- [x] Defer +- [x] Panic +- [ ] GC +- [ ] Go-routines + +#### Device drivers +- Console + - [x] Text-mode console + - [x] Vesa-fb (15, 16, 24 and 32 bpp) console with support for bitmap fonts and (optional) logo +- TTY + - [x] Simple VT +- ACPI 6.2 support (**in progress**) + - [ ] ACPI table detection and parsing + - [ ] AML parser/interpreter +- Interrupt handling chip drivers + - [ ] APIC +- Timer and time-keeping drivers + - [ ] APM timer + - [ ] APIC timer + - [ ] HPET + - [ ] RTC +- Timekeeping system + - [ ] Monotonic clock (configurable timer implementation) +### Feature roadmap + +Here is a list of features planned for the future: +- RAMDISK support (tar/bz2) +- Loadable modules (using a mechanism analogous to Go plugins) +- Tasks and scheduling +- Network device drivers +- Hypervisor support +- POSIX-compliant VFS From 63e9f40d47fe9a0ca4ace446e462049f835c3821 Mon Sep 17 00:00:00 2001 From: Achilleas Anagnostopoulos Date: Tue, 8 Aug 2017 22:58:14 +0100 Subject: [PATCH 2/3] Add build guide --- BUILD.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 BUILD.md diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..f14c788 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,75 @@ +## Building running and debugging gopher-os + +The project Makefile contains targets for building either the kernel image or +a bootable ISO while running on Linux or OSX. + +## Building on Linux + +To compile gopher-os wheh running on Linux you need a fairly recent version of: +- binutils (>= 2.26.0) +- xorriso +- grub +- nasm +- gcc (for GNU ld) +- go (1.6+; recommended: 1.8) + +The above dependencies can be installed using the appropriate package manager +for each particular Linux distribution. + +## Building on OSX + +To properly link the kernel object files so that the bootloader can pick up the +multi-boot signature we need to be able to control the linker configuration. For +the time being this is only possible when using GNU ld ([lld](https://lld.llvm.org/) +is a potential alternative but doesn't yet fully support linker scripts). + +You can still build the kernel using [vagrant](https://www.vagrantup.com/). For +this purpose, a Vagrantfile is provided so all you need to do is just install +vagrant on your machine and run `vagrant up` before running any of the following +make commands. + +## Supported Makefile build targets + +The project Makefile will work on both Linux and OSX (using vagrant) targets. +When running under OSX, the Makefile will ensure that all build-related commands +actually run inside the vagrant box. The following build targets are +supported: +- `kernel`: compile the code into an elf32 binary. +- `iso`: compile the code and build a bootable ISO using grub as the + bootloader. + +## Booting the gopher-os ISO file + +Once the kernel ISO is successfully built, either [qemu](http://www.qemu-project.org/) or +[virtualbox](https://www.virtualbox.org/) can be used to boot it. The Makefile +provides handy targets for doing this: +- `make run-qemu` +- `make run-vbox` + +## Supported kernel command line options + +To apply any of the following command line arguments there are two options: +1) patch [grub.cfg](src/arch/x86_64/script/grub.cfg) before building the kernel image and + append the required command line arguments at the end of the lines starting with `multiboot2` +2) alternatively, you can boot the ISO, wait for the grub menu to appear and press `e`. This + will bring up an editor where you can modify the command line before booting the kernel. + +The following command line options are currently supported: + +| Command | Description +|-----------------------|------------- +|consoleFont=$fontName | use a particular font name (e.g terminus10x18). This option is only used by console drivers supporting bitmap fonts. The set of built-in fonts is located [here](src/gopheros/device/video/console/font). If this option is not specified, the console driver will pick the best font size for the console resolution +|consoleLogo=off | disable the console logo. This option is only valid for console drivers that support logos. + +## Debugging the kernel + +If you wish to debug the kernel, you need to install gdb. Unfortunately the +gdb version that ships with most Linux distributions (and also the one that +can be installed with `brew` on OSX) has a bug which prevents gdb from properly +handling CPU switches from 32-bit protected to 64-bit long mode. This causes +problems when trying to debug the kernel while it is running on qemu. The +solution to this problem is to manually compile and install a patched gdb version which is +available [here](https://github.com/phil-opp/binutils-gdb). + +The Makefile provides a `gdb` target which compiles the kernel, builds the ISO +file, launches qemu and attaches an interactive gdb session to it. From b5bd7da0464841c1d4fe9cccc989b6e6136a436f Mon Sep 17 00:00:00 2001 From: Achilleas Anagnostopoulos Date: Tue, 8 Aug 2017 22:58:28 +0100 Subject: [PATCH 3/3] Update readme --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3a1fa4d..0a6d771 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,48 @@ -# gopheros +# gopher-os [![Build Status](https://travis-ci.org/achilleasa/gopher-os.svg?branch=master)](https://travis-ci.org/achilleasa/gopher-os) [![codecov](https://codecov.io/gh/achilleasa/gopher-os/branch/master/graph/badge.svg)](https://codecov.io/gh/achilleasa/gopher-os) [![Go Report Card](https://goreportcard.com/badge/github.com/achilleasa/gopher-os)](https://goreportcard.com/report/github.com/achilleasa/gopher-os) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -Let's write an experimental OS in Go! +The goal of this project is to build a 64-bit POSIX-compliant tick-less kernel +with a Linux-compatible syscall implementation using [Go](https://golang.org). + +This project is not about building yet another OS but rather exists to serve as +proof that Go is indeed a suitable tool for writing low level code that runs +at ring-0. + +**Note**: This project is still in the early stages of development and is not yet +in a usable state. In fact, if you build the ISO and boot it, the kernel will +eventually panic with a `Kmain returned` error. + +To find out more about the current project status and feature roadmap take a +look at the [status](STATUS.md) page. + +## Building and running gopher-os + +TLDR version: `make run-qemu` or `make run-vbox`. + +A detailed guide about building, running and debugging gopher-os on +Linux/OSX as well as the list of supported boot command line options are +available [here](BUILD.md). + +## How does it look? + +80x25 (stadard 8x16 font): ![80x25 with standard 8x16 font][cons-80x25] + +1024x768 (10x18 font): ![1024x768x32 with 10x18 font][cons-1024x768] + +2560x1600 (14x28 font): ![retina mode (2560x1600) with 14x28 font][cons-2560x1600] + +[cons-80x25]: https://drive.google.com/uc?export=download&id=0Bz9Vk3E_v2HBb3NHY1JtTFFZckU +[cons-1024x768]: https://drive.google.com/uc?export=download&id=0Bz9Vk3E_v2HBZ1M3MTNjc3NaOXM +[cons-2560x1600]: https://drive.google.com/uc?export=download&id=0Bz9Vk3E_v2HBbjBNSEJlTmJTelE + +## Contributing + +gopher-os is Open Source. Feel free to contribute! To get started take a look +at the contributing [guide](CONTRIBUTING.md). + +## Licence + +gopher-os is distributed under the [MIT](LICENSE) license.