Skip to content

Latest commit

 

History

History
126 lines (109 loc) · 9.49 KB

README.md

File metadata and controls

126 lines (109 loc) · 9.49 KB
Raw

Minoca OS

Minoca OS is a general purpose operating system written from scratch. It aims to be lean, maintainable, modular, and compatible with existing software. It features a POSIX-like interface towards application software, and a growing suite of popular packages already built and ready to go. On the backend, it contains a powerful driver model between device drivers and the kernel. The driver model enables drivers to be written in a forward compatible manner, so that kernel level components can be upgraded without necessarily requiring a recompilation of all device drivers.

Minoca OS is event driven, preemptible, SMP ready, and network capable. It currently runs on x86 PCs and a range of ARM boards.

Screenshots

Installing Git on Minoca OS Memory Profiler Stack Profiler

Getting Started

If you're just looking to try out Minoca OS, head over to our download page to grab the latest stable images. The rest of this page describes how to use this repository to build your own custom image of Minoca OS.

Building Minoca OS

The paragraphs below will get you from a fresh clone to a built image.

Environment

The Minoca OS build environment is keyed off of a few environment variables you'll need to set in order to orient the build system:

  • SRCROOT - Contains the absolute path to the base source directory. This respository is expected to be in a directory called os inside SRCROOT. If the third-party or tools repositories are present, they should be in directories called third-party and tools respectively underneath SRCROOT. For example, if you had checked out this repository into ~/src/os, then in your shell you'd run export SRCROOT=~/src.
  • ARCH - Contains the architecture to build Minoca OS for (aka the target architecture). Valid values are armv6, armv7, and x86.
  • VARIANT - Contains the architecture variant, if any. Leave this unset most of the time. Currently the only valid value is q for the x86 architecture, which builds for the Intel Quark.
  • DEBUG - Describes whether to build Minoca OS for debugging or release. Valid values are dbg for debug or rel for release. We always build dbg.
  • PATH - You'll need to have $SRCROOT/$ARCH$VARIANT$DEBUG/tools/bin in your path to build successfully.

Prerequisites

To build Minoca OS you'll need a Minoca-specific toolchain for the particular architecture you're building. Prebuilt toolchains can be found here. If you want to build the toolchain from sources, you'll need to check out the third-party repository and run "make tools" in there.

Note: If you want to build your own toolchain on Windows, you may find the tools repository helpful, as it contains a native MinGW compiler, make, and other tools needed to bootstrap a toolchain on Windows.

Build

Run make to build the OS for the particular architecture you've supplied. Parallel make is supported. The final output of the build will be several .img files located in $SRCROOT/$ARCH$VARIANT$DEBUG/bin/*.img. For example, the PC image is usually located at $SRCROOT/x86dbg/bin/pc.img. This is a raw hard disk file that can be applied directly to a hard drive or USB stick to boot Minoca OS. The image install.img is a generic installation archive that the msetup tool can use to create new Minoca OS installations on target disks or partitions.

Object files are generated in $SRCROOT/$ARCH$VARIANT$DEBUG/obj/os. You can run make clean, or simply delete this directory, to cause the os repository to completely rebuild. Alternatively, you can run make wipe to delete all generated files, including the third-party tools you built or downloaded. Running make wipe simply deletes $SRCROOT/$ARCH$VARIANT$DEBUG/. We usually stick to make clean since make wipe requires a complete rebuild of the toolchain.

A note for macOS users: We've managed to build successfully using both GCC from XCode 8 (really clang) and Homebrew GCC, both using the 10.12 SDK. Some users have reported that they need to export SDKROOT=$(xcrun --show-sdk-path) to build properly.

Running

To boot your built images, you can write the appropriate image for the platform you're trying to boot to a USB flash drive or hard disk. On Windows, you can use the Win32DiskImager tool (included in the tools repository under win32/Win32DiskImager). You can also use the msetup tool to build custom images. If you use the msetup tool to install Minoca OS onto a partition of a disk containing other partitions that you care about (such as on the same machine you're building from), we highly recommend making a complete backup of your disk. Minoca OS is still new, and we wouldn't want a bad bug to wipe out all your data.

If you're building Minoca OS on Windows and have downloaded the tools repository, several shortcuts have been set up to allow you to quickly run a Qemu instance with the images you've just built. Make sure you fired up the development environment with the setenv.cmd script. Type run, then dx to fire up an x86 Qemu instance of pc.img with a kernel debugger attached. We use this internally for faster development. If building for ARM, it's runarm and da.

Nickel Tour

Below is a brief orientation of a few of the directories in the repository. Check the Makefile in each directory for a more detailed description of what that directory contains.

  • apps - User mode applications and libraries
    • ck - Chalk, an embeddable scripting language
    • debug - Debugger application
    • libc - The Minoca OS C Library
    • osbase - The Minoca kernel API library
    • setup - The msetup build tool
    • swiss - POSIX tools in a box
  • boot - Executables used during system boot
    • mbr - The Master Boot Record
    • fatboot - The Volume Boot Record for FAT file systems
    • bootman - The Minoca Boot Manager
    • loader - The Minoca OS loader
    • lib - Libraries shared across multiple boot executables
  • drivers - Device drivers
    • acpi - ACPI platform driver, with AML interpreter
    • fat - FAT file system driver
    • gpio - GPIO core library and SoC drivers
    • net - Networking support
      • ethernet - Wired ethernet controller drivers
      • net80211 - Core 802.11 support
      • netcore - Core networking support (TCP, UDP, IP, ARP, etc)
      • wireless - 802.11 wireless controller drivers
    • pci - PCI support
    • sd - SD/MMC support
    • spb - Serial Peripheral Bus drivers (I2C, SPI)
    • special - Special devices (/dev/null, full, zero)
    • usb - USB support
      • ehci - EHCI host controller support
      • usbcomp - USB composite device support
      • usbhid - USB HID support
      • usbhub - USB hub support
      • usbkbd - USB keyboard support
      • usbmass - USB mass storage support
      • usbmouse - USB mouse support
    • input - User input drivers
    • videocon - Video terminal console driver
  • images - Recipes to create the final images for each supported platform
  • include - Public header files
  • kernel - The Minoca OS kernel
    • ke - High level executive functions
    • mm - Memory management
    • io - Input/Output subsystem
    • kd - Kernel debug support
    • hl - Low level hardware layer support
    • ob - Object management
    • ps - Process and thread management
    • sp - System profiler support
  • lib - Common libraries used throughout boot, kernel, and user mode.
    • basevid - Library for drawing text on a framebuffer
    • fatlib - FAT file system library
    • im - ELF/PE image library
    • partlib - Partition library
    • rtl - General runtime library (printf, date/time, memcpy, etc)
    • termlib - Terminal support library
  • tasks - Internal automation configuration
  • uefi - Minimal UEFI implementation for platforms supported by Minoca OS.
    • core - Platform-agnostic UEFI firmware core
    • dev - UEFI device libraries
    • plat - Recipes and code for specific platforms
      • beagbone - BeagleBone Black firmware
      • bios - UEFI over BIOS firmware
      • integcp - Integrator/CP firmware (for ARM Qemu)
      • panda - TI PandaBoard firmware
      • rpi - Raspberry Pi 1 firmware
      • rpi2 - Raspberry Pi 2 and 3 firmware
      • veyron - Asus C201 Chromebook firmware
    • tools - Tools used in building final firmware images

Contributing

Submissions are welcome! See our CONTRIBUTING.md page for details, or our WISHLIST page for suggestions. Bugs can be reported here on Github.

License

Minoca OS is licensed to the public under the terms of the GNU General Public License, version 3. Alternate licensing options are available. Contact [email protected] if your company is interested in licensing Minoca OS. For complete licensing information, see the LICENSE file in this repository.

Contact