From 626fa782c3f31c789384b719bd1b76712efb7e88 Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Sun, 28 Sep 2014 23:25:32 +0800
Subject: [PATCH] doc: add installation instructions

---
 doc/manual/index.rst      |  2 +-
 doc/manual/installing.rst | 74 +++++++++++++++++++++++++++++++++++++++
 llvm_or1k_setup.txt       | 19 ----------
 3 files changed, 75 insertions(+), 20 deletions(-)
 create mode 100644 doc/manual/installing.rst
 delete mode 100644 llvm_or1k_setup.txt

diff --git a/doc/manual/index.rst b/doc/manual/index.rst
index e46b2e958..0b22457f6 100644
--- a/doc/manual/index.rst
+++ b/doc/manual/index.rst
@@ -6,5 +6,5 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   installing
    core_reference
-
diff --git a/doc/manual/installing.rst b/doc/manual/installing.rst
new file mode 100644
index 000000000..7540bc4a3
--- /dev/null
+++ b/doc/manual/installing.rst
@@ -0,0 +1,74 @@
+Installing ARTIQ
+================
+
+Preparing the core device FPGA board
+************************************
+
+You may skip those steps if the board is already flashed.
+
+You will need:
+  * FPGA vendor tools (e.g. Xilinx ISE or Vivado)
+  * OpenRISC GCC/binutils toolchain (or1k-elf-...)
+  * Python 3.3+ (note: in this document, the ``python`` command refers to Python 3)
+  * Migen and MiSoC (http://m-labs.hk/gateware.html)
+
+After these components are installed, build and flash the bitstream and BIOS by running `from the MiSoC top-level directory`: ::
+
+  $ ./make.py -X /path_to/ARTIQ/soc -t artiq all
+
+Then, build and flash the ARTIQ runtime: ::
+
+  $ cd /path_to/ARTIQ/soc/runtime
+  $ make flash
+
+Check that the board boots by running a serial terminal program (you may need to press its FPGA reconfiguration button or power-cycle it to load the bitstream that was newly written into the flash): ::
+
+  $ flterm --port /dev/ttyUSB1
+  MiSoC BIOS   http://m-labs.hk
+  [...]
+  Booting from flash...
+  Loading xxxxx bytes from flash...
+  Executing booted program.
+  ARTIQ runtime built <date/time>
+
+The communication parameters are 115200 8-N-1.
+
+Installing the host-side software
+*********************************
+
+The main dependency of ARTIQ is LLVM and its Python bindings (http://llvmpy.org). Currently, this installation is tedious because of the OpenRISC support not being merged upstream LLVM and because of incompatibilities between the versions of LLVM that support OpenRISC and the versions of LLVM that support the Python bindings. ::
+
+  git clone checkout https://github.com/openrisc/llvm-or1k
+  cd llvm-or1k
+  git checkout b3a48efb2c05ed6cedc5395ae726c6a6573ef3ba
+  patch -p1 < /path_to/ARTIQ/patches/llvm/*
+
+  cd tools
+  git clone https://github.com/openrisc/clang-or1k clang
+  cd clang
+  git checkout 02d831c7e7dc1517abed9cc96abdfb937af954eb
+  patch -p1 < /path_to/ARTIQ/patches/clang/*
+
+  cd ../..
+  mkdir build && cd build
+  ../configure --prefix=/usr/local/llvm-or1k
+  make ENABLE_OPTIMIZED=1 REQUIRES_RTTI=1
+  sudo -E make install ENABLE_OPTIMIZED=1 REQUIRES_RTTI=1
+
+  cd ../..
+  git clone https://github.com/llvmpy/llvmpy
+  cd llvmpy
+  git checkout llvm-3.4
+  git checkout 7af2f7140391d4f708adf2721e84f23c1b89e97a
+  patch -p1 < /path_to/ARTIQ/patches/llvmpy/*
+  LLVM_CONFIG_PATH=/usr/local/llvm-or1k/bin/llvm-config sudo -E python setup.py install
+
+You may want to use ``checkinstall`` instead of ``make install`` (which registers the installation with your package manager) and ``pip3 install --user .`` instead of ``sudo -E python setup.py install``.
+
+You can then install ARTIQ itself: ::
+
+  cd /path_to/ARTIQ
+  sudo python setup.py
+
+Alternatively, you can simply add the ARTIQ directory to your ``PYTHONPATH`` environment variable. The advantage of this technique is that you will not need to reinstall ARTIQ when modifying or upgrading it, which is useful during development.
+
diff --git a/llvm_or1k_setup.txt b/llvm_or1k_setup.txt
deleted file mode 100644
index 380698064..000000000
--- a/llvm_or1k_setup.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-checkout https://github.com/openrisc/llvm-or1k
-commit b3a48efb2c05ed6cedc5395ae726c6a6573ef3ba
-into $LLVM_SRC
-apply patches/llvm/*
-
-checkout https://github.com/openrisc/clang-or1k
-commit 02d831c7e7dc1517abed9cc96abdfb937af954eb
-into $LLVM_SRC/tools/clang
-apply patches/clang/*
-
-in $LLVM_SRC
-./configure --prefix=/usr/local/llvm-or1k
-make ENABLE_OPTIMIZED=1 REQUIRES_RTTI=1
-ENABLE_OPTIMIZED=1 sudo -E checkinstall
-
-checkout https://github.com/llvmpy/llvmpy
-branch: llvm-3.4, 7af2f7140391d4f708adf2721e84f23c1b89e97a
-apply patches/llvmpy/*
-LLVM_CONFIG_PATH=/usr/local/llvm-or1k/bin/llvm-config pip3 install --user .