Converted the README file with rst format so that it can be easily converted
[barrelfish] / README
diff --git a/README b/README
index a154a65..b58222e 100644 (file)
--- a/README
+++ b/README
@@ -7,14 +7,16 @@ 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
+SUPPORTED HARDWARE
+--------------------------------
 
 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
+
+   - 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.
@@ -22,6 +24,7 @@ Barrelfish currently runs on:
 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
@@ -31,8 +34,8 @@ 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 
+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
@@ -44,102 +47,118 @@ note that the e1000 device emulated by QEMU is not supported by our driver.
 
 
 REQUIRED TOOLS
+--------------------------------
 
 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
+
+   - 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_.
  * GNU binutils (2.19 is known to work)
  * GNU make
  * GHC v7.4 and Parsec 3.1
-   * older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.1
-   * GHC v6.12.1 has a known bug and is unable to build our tools
-   * earlier versions of GHC are unsupported
+   - older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.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 a
 recent Debian or Ubuntu system, as these are what we use.
 
 
+.. _CodeSourcery: http://www.codesourcery.com/sgpp/lite/arm
+
 BUILDING
+--------------------------------
+
+1. Assuming you have already unpacked the sources, create a build directory ::
+
+    $ mkdir build && cd build
 
-1. Assuming you have already unpacked the sources, create a build directory:
-$ mkdir build && cd build
+1. Run ``hake.sh``, giving it the path to the source directory and target
+architecture(s) ::
+
+    $ ../hake/hake.sh .. 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 ARCH=x86_64
 
 
 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/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
+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.
-Note: Chips is no longer supported. The SKB now also serves as a name service.
+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.
 
-
 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
+--------------------------------
 
 Q: How do I run a program?
 A: Add it to the boot sequence by specifying the module in your menu.lst file.
@@ -175,3 +194,4 @@ A: http://www.barrelfish.org/
 
 Q: Can I contribute?
 A: We'd certainly like to hear from you. Please send us mail.
+