Add License and initial README

2 files changed, 62 insertions, 0 deletions

diff --git a/COPYING b/COPYING
new file mode 100644
index 0000000..f2389e5
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,9 @@
+Copyright (C) 2018-2019 Daniel Friesel <daniel.friesel@uos.de>
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..009d284
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+multipass - a multi-architecture library operating system
+---------------------------------------------------------
+
+multipass aims to aid development and evaluation of operating system components
+on a diverse set of architectures. It provides a basic set of drivers (e.g.
+for standard output on a serial interface) and tries to get out of the way
+as much as possible.
+
+multipass is single-threaded by design. At compile-time, the switch `app=...`
+selects an application, which must implement `int main(void)` and do
+everything itself from that point on. When using `loop=1`, users must also
+implement `void loop(void)`, which will be executed roughly once per second
+- but only if the main application is idle.
+
+# Getting Started
+
+The compilation process is controlled by the Makefile, which also contains
+targets for flashing microcontrollers, info, and help output. Most targets
+require two mandatory arguments: `arch` (target architecture) and `app`
+(which application to build and run). Operating system behaviour is fine-tuned
+using additional (optional) flags, which may be set both on the command line
+and in an application Makefile.
+
+To avoid redundancy in the typical `make program arch=... app=... && make monitor
+arch=... app=...` workflow, two helper scripts are provided:
+
+* `./mp` is a shortcut for `make info` and `make program` (build and flash)
+* `./mpm` is a shortcut for `make info`, `make program`, and `make monitor` (build, flash, and monitor output)
+
+Flags are passed to each `make` invocation.
+
+For a quick start, try ledblink:
+
+`./mpm arch=posix app=ledblink`
+
+You should see some data about the compilation process, "Hello, world!", and
+some numbers. As POSIX is a fake-architecture (it builds an ELF binary which
+is executed directly on Linux), you do not need a microcontroller to run it.
+Terminate execution using Ctrl+C.
+
+To see the blinkenlights, there's an optional (`arch=posix`-specific) flag:
+
+`./mpm arch=posix app=ledblink gpio_trace=1`
+
+Now, you should see a simulated LED being toggled every second.
+
+# Supported Architectures, Drivers, and Flags
+
+To see all supported architectures, run `make help arch=posix`. It will also
+show architecture-independent flags and drivers.
+
+For architecture-specific options, set the `arch` flag, e.g.
+`make help arch=arduino-nano`.