Merge pull request #49 from achilleasa/improve-readme

Improve documentation

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.

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)

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.

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