kernel: do not drop RAM caps
[barrelfish] / README
diff --git a/README b/README
index e6ab861..05bc2d7 100644 (file)
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
 ##########################################################################
-Copyright (c) 2009-2012, ETH Zurich.
+Copyright (c) 2009-2013, ETH Zurich.
 All rights reserved.
 
 This file is distributed under the terms in the attached LICENSE file.
@@ -7,20 +7,55 @@ If you do not find this file, copies can be found by writing to:
 ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
 ##########################################################################
 
-"SUPPORTED" HARDWARE
+Barrelfish Overview
+--------------------------------
 
 Barrelfish currently runs on:
+
  * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
-   * Intel Xeon: Clovertown, Gainestown, Beckton
-     (X5355, E5520, X7560, L5520, L7555)
-   * AMD Opteron: Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
-     (2220, 8350, 8374, 8380, 8431, 6174)
- * Intel Single-Chip Cloud Computer (SCC), both Copper Ridge and Rocky Lake
-   are known to work.
+
+   - Intel Xeon Clovertown, Gainestown, Beckton, IvyBridge, Haswell (X5355,
+     E5520, X7560, L5520, L7555, E5-2670v2, E3-1245v3)
+   - AMD Opteron Italy, Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
+     (275, 2220, 8350, 8374, 8380, 8431, 6174)
+   - QEMU simulator (2.0.0)
+
+ * ARM CPUs, specifically ARMv7 and ARMv5. The following platforms are known to work:
+
+   - The integratorcp ARMv5 machine as simulated by QEM
+   - The Texas Instruments OMAP4460 Pandaboard ES SoC
+     (Barrelfish runs on both the A9 and the M3 cores)
+   - The ARM VExpress EMM board as simulated by GEM5
+   - There is also limited support for the Netronome i8000 card, incorporating
+     a single Intel iXP2800 processor
+
+This README file provides instructions for the x86 architecture. For other
+architectures, please refer to the architecture-specific technical notes (e.g.,
+see TN 06 for the SCC, and TN 17 for ARM).
+
+You can either generate the latest documentation from this source-code
+(instructions at end of this file), or visit the Barrelfish_ website
+to download them.
+
+.. _Barrelfish: http://www.barrelfish.org/
+
+Supported PC hardware
+--------------------------------
+
+Barrelfish supports following PC hardware :
+
+ * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
+
+   - Intel Xeon Clovertown, Gainestown, Beckton, Ivy Bridge, Haswell (X5355,
+     E5520, X7560, L5520, L7555, E5-2670v2, E3-1245v3)
+   - AMD Opteron Italy, Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
+     (275, 2220, 8350, 8374, 8380, 8431, 6174)
+      * Note: the Opteron 275 do not work in IA-32 mode.
 
 The biggest compatibility problems are likely to be in the PCI/ACPI code. We
 usually discover new quirks (or missing functionality in the ACPI glue code)
 on each new machine we test. The following systems are known to work:
+
  * Intel x5000XVN
  * Tyan n6650W and S4985
  * Supermicro H8QM3-2
@@ -30,10 +65,6 @@ on each new machine we test. The following systems are known to work:
  * Lenovo X200 and X301 laptops
  * ASUS Eee PC 1015PEM netbooks
 
-In addition, a port to the ARM architectures is in progress. This is 
-less complete than the x86 and SCC ports, and not described in this 
-document, but feel free to ask for help on the mailing list.
-
 The e1000n driver should work with most recent Intel gigabit ethernet
 controllers (see the list in devices/e1000.dev). We've mostly used the
 82572EI (PCI device ID 0x1082).
@@ -41,102 +72,132 @@ controllers (see the list in devices/e1000.dev). We've mostly used the
 You should also be able to boot Barrelfish on a recent version of QEMU (0.14);
 note that the e1000 device emulated by QEMU is not supported by our driver.
 
+Required Tools
+--------------------------------
 
-REQUIRED TOOLS
+We are making sure that Barrelfish and its tools can be built using the
+following:
 
-The following are required to build Barrelfish and its tools:
- * GCC 4.x
-   * 4.4.5, and 4.5.2 are known to work
-   * cross-compiling between i386 and x86_64 works
-     (requires libc6-dev-i386 to build 32 bit on 64 bit machine)
-   * for the ARM port, we recommend the EABI tools available from CodeSourcery:
-     http://www.codesourcery.com/sgpp/lite/arm
- * GNU binutils (2.19 is known to work)
+ * GCC 4.8.2 for x86_64 and x86_32
+   - cross-compiling between i386 and x86_64 works (install gcc-multilib on 64 bit Ubuntu LTS)
+ * GCC 4.7.3 for ARMv5 and ARMv7
+   - gcc-arm-linux-gnueabi and g++-arm-linux-gnueabi on Ubuntu LTS
+ * GNU binutils (2.24 is known to work)
  * GNU make
- * GHC v6.10 or v6.12.2 and Parsec 2.1
-   * earlier versions of GHC are unsupported
-   * GHC v6.12.1 has a known bug and is unable to build our tools
+ * GHC v7.6.3 and Parsec 3.1
+   - older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.1 or
+     v7.4 with Parsec 3.1
+   - GHC v6.12.1 has a known bug and is unable to build our tools
+   - earlier versions of GHC are unsupported
+
+Our build system may not be very portable; if in doubt, try building on the
+latest Ubuntu LTS system (14.04.1), as this is what we use to run nightly
+tests.
 
-Our build system may not be very portable; if in doubt, try building on a
-recent Debian or Ubuntu system, as these are what we use.
 
+Building
+--------------------------------
 
-BUILDING
+1. Assuming you have already unpacked the sources, create a build directory ::
 
-1. Assuming you have already unpacked the sources, create a build directory:
-$ mkdir build && cd build
+    $ mkdir build && cd build
+
+1. Run ``hake.sh``, giving it the path to the source directory and target
+architecture(s) ::
+
+    $ ../hake/hake.sh -s ../ -a x86_64
 
-2. Run hake.sh, giving it the path to the source directory and target architecture(s):
-$ ../hake/hake.sh .. x86_64
 This will configure the build directory and use GHC to compile and then run
-hake, a tool used to generate the Makefile.
+hake, a tool used to generate the ``Makefile``.
+
+3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
+run ``make rehake`` to apply them.
+
+4. Run make, and wait ::
 
-3. Optionally, edit the configuration parameters in hake/Config.hs and run
- 'make rehake' to apply them.
+    $ make
 
-4. Run make, and wait...
-$ make
+5. If everything worked, you should now be able to run Barrelfish inside QEMU ::
 
-5. If everything worked, you should now be able to run Barrelfish inside QEMU:
-$ make sim ARCH=x86_64
+    $ make sim
 
 
-INSTALLING AND BOOTING
+Installing and Booting
+--------------------------------
 
 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
 Your options are either:
+
  * use the pre-loader "elver" that can be found in the tools directory
- * patch GRUB to support a 64-bit kernel image, using the patch found here:
-   http://savannah.gnu.org/bugs/?17963
+ * patch GRUB to support a 64-bit kernel image, using this patch_.
+
+.. _patch: http://savannah.gnu.org/bugs/?17963
 
 "Installing" Barrelfish currently consists of copying the ELF files for the CPU
 driver and user programs to a location that the target machine can boot from,
 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
 programs to load and the arguments to pass them.
 
-If you specify an appropriate INSTALL_PREFIX, 'make install' will copy the
-binaries to the right place for you, eg:
-$ make install INSTALL_PREFIX=/tftpboot/barrelfish
+If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
+binaries to the right place for you, eg ::
+
+    $ make install INSTALL_PREFIX=/tftpboot/barrelfish
 
 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
 also works. Instructions for setting up GRUB to do this are beyond the scope of
 this document. Assuming you have such a setup, here is a sample menu.lst file
 for a basic diskless boot that doesn't do anything useful beyond probing the
-PCI buses and starting a basic shell:
-
-title   Barrelfish
-root    (nd)
-kernel /barrelfish/x86_64/sbin/elver
-module /barrelfish/x86_64/sbin/cpu
-module /barrelfish/x86_64/sbin/init
-module /barrelfish/x86_64/sbin/mem_serv
-module /barrelfish/x86_64/sbin/monitor
-module /barrelfish/x86_64/sbin/chips boot
-module /barrelfish/x86_64/sbin/ramfsd boot
-module /barrelfish/x86_64/sbin/skb boot
-modulenounzip /barrelfish/skb_ramfs.cpio.gz nospawn
-module /barrelfish/x86_64/sbin/pci boot
-module /barrelfish/x86_64/sbin/spawnd boot
-module /barrelfish/x86_64/sbin/serial
-module /barrelfish/x86_64/sbin/fish
+PCI buses and starting a basic shell ::
+
+    title   Barrelfish
+    root    (nd)
+    kernel /barrelfish/x86_64/sbin/elver
+    module /barrelfish/x86_64/sbin/cpu
+    module /barrelfish/x86_64/sbin/init
+    module /barrelfish/x86_64/sbin/mem_serv
+    module /barrelfish/x86_64/sbin/monitor
+    module /barrelfish/x86_64/sbin/ramfsd boot
+    module /barrelfish/x86_64/sbin/skb boot
+    modulenounzip /barrelfish/skb_ramfs.cpio.gz nospawn
+    module /barrelfish/x86_64/sbin/acpi boot
+    module /barrelfish/x86_64/sbin/pci boot
+    module /barrelfish/x86_64/sbin/spawnd boot
+    module /barrelfish/x86_64/sbin/serial
+    module /barrelfish/x86_64/sbin/fish
 
 There are many other programs you can load (take a look around the usr tree for
-examples). To start a program on a core other than the BSP core, pass 'core=N'
-as its first argument.
+examples). To start a program on a core other than the BSP core, pass
+``core=N`` as its first argument.
 
 If things work, you should see output on both the VGA console and COM1.
 
+Generating Documentation
+--------------------------------
+
+Barrelfish documentation can be found on Barrelfish website
+(http://www.barrelfish.org/). And it can be also generated from the code tree.
+For documentation generation, you will need ``latex`` packages installed,
+including support for ``pdflatex``.  Following are the instructions for
+generating the documentation assuming you have already unpacked the sources ::
+
+    $ mkdir build && cd build
+    $ ../hake/hake.sh -s ../
+    $ make docs
 
-KNOWN ISSUES
+You will find all the technotes in ``docs/`` directory.
+
+Known Issues
+--------------------------------
 
 There are many. Those you're likely to encounter include:
+
  * The documentation is incomplete and out of date.
  * Some drivers and user programs are known not to build, and are
    not included in the default set of targets (MODULES) in the Makefile.
 
-
-LIKELY FAQs
+Likely FAQs
+--------------------------------
 
 Q: How do I run a program?
 A: Add it to the boot sequence by specifying the module in your menu.lst file.
@@ -169,6 +230,49 @@ A: Maybe. There are two options at the moment:
 
 Q: Where can I find more information, including papers and new releases?
 A: http://www.barrelfish.org/
+   http://wiki.barrelfish.org/
 
 Q: Can I contribute?
-A: We'd certainly like to hear from you. Please send us mail.
+A: We'd certainly like to hear from you. Feel free to send pateches (or even
+   git merge requests) to the Barrelfish mailing list.
+
+   To keep track of contributions to Barrelfish, we use a sign-off procedure
+   similar to the Linux kernel:
+
+   The sign-off is a simple line at the end of the explanation for the patch,
+   which certifies that you wrote it or otherwise have the right to pass it on
+   as an open-source patch.  The rules are pretty simple: if you can certify
+   the below:
+
+        Developer's Certificate of Origin 1.1
+
+        By making a contribution to this project, I certify that:
+
+        (a) The contribution was created in whole or in part by me and I
+            have the right to submit it under the open source license
+            indicated in the file; or
+
+        (b) The contribution is based upon previous work that, to the best
+            of my knowledge, is covered under an appropriate open source
+            license and I have the right under that license to submit that
+            work with modifications, whether created in whole or in part
+            by me, under the same open source license (unless I am
+            permitted to submit under a different license), as indicated
+            in the file; or
+
+        (c) The contribution was provided directly to me by some other
+            person who certified (a), (b) or (c) and I have not modified
+            it.
+
+        (d) I understand and agree that this project and the contribution
+            are public and that a record of the contribution (including all
+            personal information I submit with it, including my sign-off) is
+            maintained indefinitely and may be redistributed consistent with
+            this project or the open source license(s) involved.
+
+   then you just add a line saying
+
+        Signed-off-by: Random J Developer <random@developer.example.org>
+
+   Note that git has support for adding such a message in the end of the commit
+   log message.