Merge branch 'docs' into work

9 files changed, 475 insertions, 102 deletions

diff --git a/host/CMakeLists.txt b/host/CMakeLists.txt
index 6334b44ff..4ef6278b9 100644
--- a/host/CMakeLists.txt
+++ b/host/CMakeLists.txt
@@ -124,24 +124,8 @@ INSTALL(
 )
 
 ########################################################################
-# Setup Docs
-########################################################################
-INCLUDE(FindDoxygen)
-
-IF(DOXYGEN_FOUND)
-    SET(CMAKE_CURRENT_BINARY_DIR_DOXYGEN ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
-    CONFIGURE_FILE(
-        ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
-        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    @ONLY)
-    ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN}
-        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-        COMMENT "Generating documentation with doxygen"
-    )
-    ADD_CUSTOM_TARGET(docs ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN})
-    INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN} DESTINATION ${PKG_DOC_DIR})
-ENDIF(DOXYGEN_FOUND)
-
+# Install Package Docs
+########################################################################
 INSTALL(FILES
     ${CMAKE_CURRENT_SOURCE_DIR}/README
     ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
@@ -152,6 +136,7 @@ INSTALL(FILES
 ########################################################################
 # Add the subdirectories
 ########################################################################
+ADD_SUBDIRECTORY(docs)
 ADD_SUBDIRECTORY(examples)
 ADD_SUBDIRECTORY(include)
 ADD_SUBDIRECTORY(lib)
diff --git a/host/README b/host/README
index cbf18dbf7..558cf0e4a 100644
--- a/host/README
+++ b/host/README
@@ -15,86 +15,4 @@ Basic RX
 Basic TX
 LF RX
 LF TX
-
-########################################################################
-# Dependencies
-########################################################################
-Unix Notes:
-    These dependencies can be acquired through the package manager.
-Windows Notes:
-    These dependencies can be acquired through installable exe files.
-    Usually, the windows installer can be found on the project's website.
-    Some projects do not host windows installers, and if this is the case,
-    follow the auxiliary download url for the windows installer (below).
-
-Git:
-    Required to check out the repository (not needed for source downloads).
-    On windows, install cygwin with git support to checkout the repository.
-
-C++:
-    On unix, this is GCC 4.0 and above. On windows, this is MSVC 2008.
-    Other compilers have not been tested yet or confirmed working.
-
-CMake:
-    Version: at least 2.8
-    Required for: build time
-    Download URL: http://www.cmake.org/cmake/resources/software.html
-
-Boost:
-    Version: at least 3.6 unix, at least 4.0 windows
-    Required for: build time + run time
-    Download URL: http://www.boost.org/users/download/
-    Download URL (windows installer): http://www.boostpro.com/download
-
-Python:
-    Version: at least 2.6
-    Required for: build time
-    Download URL: http://www.python.org/download/
-
-Cheetah:
-    Version: at least 2.0
-    Required for: build time
-    Download URL: http://www.cheetahtemplate.org/download.html
-    Download URL (windows installer): http://feisley.com/python/cheetah/
-
-Doxygen:
-    Required for: build time (optional)
-    Download URL: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
-
-########################################################################
-# Build Instructions (unix)
-########################################################################
-cd <uhd-repo-path>/host
-mkdir build
-cd build
-cmake ../
-make
-make test
-sudo make install
-
-For a custom prefix, use: cmake -DCMAKE_INSTALL_PREFIX=<myprefix> ../
-
-########################################################################
-# Build Instructions (windows)
-########################################################################
-
-##### Generate the project with cmake #####
-Open the cmake gui program.
-Set the path to the source code: <uhd-repo-path>/host
-Set the path to the build directory: <uhd-repo-path>/host/build
-Make sure that the paths do not contain spaces.
-Click configure and select the MSVC compiler.
-Set the build variables and click configure again.
-Click generate and a project file will be created in the build directory.
-
-##### Build the project in MSVC #####
-Open the generated project file in MSVC.
-Select the build all target, right click, and choose build.
-Select the install target, right click, and choose build.
-    Note: you may not have permission to build the install target.
-    You need to be an administrator or to run MSVC as administrator.
-
-##### Setup the PATH environment variable #####
-Add the boost library path and uhd library path to your %PATH%.
-Usually c:\program files\boost\<version>\lib and c:\program files\uhd\lib
-
+RFX Series
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
new file mode 100644
index 000000000..52376fe8c
--- /dev/null
+++ b/host/docs/CMakeLists.txt
@@ -0,0 +1,82 @@
+#
+# Copyright 2010 Ettus Research LLC
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+########################################################################
+# List of manual sources
+########################################################################
+SET(manual_sources
+    index.rst
+    build.rst
+    usrp2.rst
+)
+
+########################################################################
+# Setup Manual
+########################################################################
+MESSAGE(STATUS "Checking for rst2html (docutils)")
+FIND_PROGRAM(RST2HTML rst2html)
+IF(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
+    MESSAGE(STATUS "Checking for rst2html (docutils) - not found")
+    MESSAGE(STATUS "  Disabled generation of HTML manual.")
+ELSE(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
+    MESSAGE(STATUS "Checking for rst2html (docutils) - found")
+    MESSAGE(STATUS "  Enabled generation of HTML manual.")
+    SET(stylesheet ${CMAKE_CURRENT_SOURCE_DIR}/style.css)
+    SET(rst2html_options
+        --stylesheet=${stylesheet}
+        --no-toc-backlinks
+        --date
+        --time
+    )
+    FOREACH(rstfile ${manual_sources})
+        SET(rstfile ${CMAKE_CURRENT_SOURCE_DIR}/${rstfile})
+        GET_FILENAME_COMPONENT(rstfile_we ${rstfile} NAME_WE)
+        SET(htmlfile ${CMAKE_CURRENT_BINARY_DIR}/${rstfile_we}.html)
+        ADD_CUSTOM_COMMAND(
+            OUTPUT ${htmlfile} DEPENDS ${rstfile} ${stylesheet}
+            COMMAND ${RST2HTML} ${rstfile} ${htmlfile} ${rst2html_options}
+            COMMENT "Generating ${htmlfile}"
+        )
+        LIST(APPEND manual_html_files ${htmlfile})
+        INSTALL(FILES ${htmlfile} DESTINATION ${PKG_DOC_DIR}/manual/html)
+    ENDFOREACH(rstfile ${manual_sources})
+    ADD_CUSTOM_TARGET(manual_html ALL DEPENDS ${manual_html_files})
+ENDIF(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
+
+INSTALL(FILES ${manual_sources} DESTINATION ${PKG_DOC_DIR}/manual/rst)
+
+########################################################################
+# Setup Doxygen
+########################################################################
+INCLUDE(FindDoxygen)
+
+IF(DOXYGEN_FOUND)
+    MESSAGE(STATUS "  Enabled generation of Doxygen documentation.")
+    SET(CMAKE_CURRENT_BINARY_DIR_DOXYGEN ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+    CONFIGURE_FILE(
+        ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    @ONLY)
+    ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN}
+        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+        COMMENT "Generating documentation with doxygen"
+    )
+    ADD_CUSTOM_TARGET(doxygen_html ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN})
+    INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN} DESTINATION ${PKG_DOC_DIR})
+ELSE(DOXYGEN_FOUND)
+    MESSAGE(STATUS "  Disabled generation of Doxygen documentation.")
+ENDIF(DOXYGEN_FOUND)
diff --git a/host/Doxyfile.in b/host/docs/Doxyfile.in
index 7395516b5..7395516b5 100644
--- a/host/Doxyfile.in
+++ b/host/docs/Doxyfile.in
diff --git a/host/docs/build.rst b/host/docs/build.rst
new file mode 100644
index 000000000..d28682764
--- /dev/null
+++ b/host/docs/build.rst
@@ -0,0 +1,130 @@
+========================================================================
+UHD - Build Guide
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+Build Dependencies
+------------------------------------------------------------------------
+
+**Unix Notes:**
+The dependencies can be acquired through the package manager.
+
+**Windows Notes:**
+The dependencies can be acquired through installable exe files.
+Usually, the windows installer can be found on the project's website.
+Some projects do not host windows installers, and if this is the case,
+follow the auxiliary download url for the windows installer (below).
+
+^^^^^^^^^^^^^^^^
+Git
+^^^^^^^^^^^^^^^^
+Required to check out the repository.
+On windows, install cygwin with git support to checkout the repository,
+or install msysgit from http://code.google.com/p/msysgit/downloads/list
+
+^^^^^^^^^^^^^^^^
+C++
+^^^^^^^^^^^^^^^^
+On unix, this is GCC 4.0 and above. On windows, this is MSVC 2008.
+Other compilers have not been tested yet or confirmed working.
+
+^^^^^^^^^^^^^^^^
+CMake
+^^^^^^^^^^^^^^^^
+* **Version:** at least 2.8
+* **Required for:** build time
+* **Download URL:** http://www.cmake.org/cmake/resources/software.html
+
+^^^^^^^^^^^^^^^^
+Boost
+^^^^^^^^^^^^^^^^
+* **Version:** at least 3.6 unix, at least 4.0 windows
+* **Required for:** build time + run time
+* **Download URL:** http://www.boost.org/users/download/
+* **Download URL (windows installer):** http://www.boostpro.com/download
+
+^^^^^^^^^^^^^^^^
+Python
+^^^^^^^^^^^^^^^^
+* **Version:** at least 2.6
+* **Required for:** build time
+* **Download URL:** http://www.python.org/download/
+
+^^^^^^^^^^^^^^^^
+Cheetah
+^^^^^^^^^^^^^^^^
+* **Version:** at least 2.0
+* **Required for:** build time
+* **Download URL:** http://www.cheetahtemplate.org/download.html
+* **Download URL (windows installer):** http://feisley.com/python/cheetah/
+
+^^^^^^^^^^^^^^^^
+Doxygen
+^^^^^^^^^^^^^^^^
+* **Required for:** build time (optional)
+* **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
+------------------------------------------------------------------------
+Build Instructions (Unix)
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Generate Makefiles with cmake
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    cd <uhd-repo-path>/host
+    mkdir build
+    cd build
+    cmake ../
+
+For a custom prefix, use: cmake -DCMAKE_INSTALL_PREFIX=<myprefix> ../
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build and install
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    make
+    make test
+    sudo make install
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setup the library path
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Make sure that libuhd.so is in your LD_LIBRARY_PATH
+or add it to /etc/ld.so.conf and make sure to run sudo ldconfig
+
+
+------------------------------------------------------------------------
+Build Instructions (Windows)
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Generate the project with cmake
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Open the cmake gui program.
+* Set the path to the source code: <uhd-repo-path>/host
+* Set the path to the build directory: <uhd-repo-path>/host/build
+* Make sure that the paths do not contain spaces.
+* Click configure and select the MSVC compiler.
+* Set the build variables and click configure again.
+* Click generate and a project file will be created in the build directory.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build the project in MSVC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Open the generated project file in MSVC.
+* Select the build all target, right click, and choose build.
+* Select the install target, right click, and choose build.
+
+**Note:** you may not have permission to build the install target.
+You need to be an administrator or to run MSVC as administrator.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setup the PATH environment variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Add the boost library path to %PATH% (usually c:\\program files\\boost\\<version>\\lib)
+* Add the uhd library path to %PATH% (usually c:\\program files\\uhd\\lib)
diff --git a/host/docs/index.rst b/host/docs/index.rst
new file mode 100644
index 000000000..51dba26b5
--- /dev/null
+++ b/host/docs/index.rst
@@ -0,0 +1,28 @@
+========================================================================
+UHD - Universal Hardware Driver
+========================================================================
+
+The UHD is the universal hardware driver for Ettus Research products.
+The goal of the UHD is to provide a host driver and api for current and future Ettus Research products.
+Users will be able to use the UHD driver standalone/without gnuradio.
+Also, a dual license option will be available for those who build against the UHD
+but cannot release their software products under the GPL.
+
+------------------------------------------------------------------------
+Contents
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^
+API Documentation
+^^^^^^^^^^^^^^^^^^^^^
+* `Doxygen <./../../doxygen/html/index.html>`_
+
+^^^^^^^^^^^^^^^^^^^^^
+Supported Devices
+^^^^^^^^^^^^^^^^^^^^^
+* `USRP2 App Notes <./usrp2.html>`_
+
+^^^^^^^^^^^^^^^^^^^^^
+Building the UHD
+^^^^^^^^^^^^^^^^^^^^^
+* `Build Guide <./build.html>`_
diff --git a/host/docs/style.css b/host/docs/style.css
new file mode 100644
index 000000000..7bd84c9c7
--- /dev/null
+++ b/host/docs/style.css
@@ -0,0 +1,102 @@
+body{
+font-family:Arial, Helvetica, sans-serif;
+font-size:10pt;
+color:black;
+background-color:#FEFEFE;
+width:90%;
+margin:0 auto 0 auto;
+}
+
+div.document div.contents{
+border:1px solid #333333;
+padding:10px 30px 10px 10px;
+margin-left:50px;
+color:inherit;
+background-color:#FCFCFC;
+display:inline-block;
+}
+
+div.document p.topic-title{
+font-weight:bold;
+}
+
+div.document a:link, div.document a:visited{
+color:#236B8E;
+background-color:inherit;
+text-decoration:none;
+}
+
+div.document a:hover{
+color:#4985D6;
+background-color:inherit;
+text-decoration:none;
+}
+
+div.document h1.title{
+font-size:150%;
+border-left:1px solid #333333;
+border-bottom:1px solid #333333;
+text-align:left;
+padding:10px 0px 10px 10px;
+margin:10px 5px 20px 5px;
+color:#333333;
+background-color:inherit;
+}
+
+div.document h2.subtitle, div.section h1{
+margin-top:50px;
+border-bottom:1px solid #333333;
+font-size:140%;
+text-align:center;
+padding:20px 0px 10px 0px;
+color:#333333;
+background-color:inherit;
+}
+
+div.section h2{
+font-size:110%;
+text-align:left;
+padding:15px 0px 5px 0px;
+text-decoration:underline;
+color:#333333;
+background-color:inherit;
+}
+
+div.document pre.literal-block{
+border:1px inset #333333;
+padding:5px;
+margin:10px 5px 10px 5px;
+color:inherit;
+background-color:#FCFCFC;
+font-size:90%;
+}
+
+div.document table{
+padding:5px;
+font-size:95%;
+}
+
+div.document th{
+padding:3px 7px 3px 7px;
+border:1px solid #333333;
+text-align:center;
+color:inherit;
+background-color:#ECECEC;
+}
+
+div.document tr{
+}
+
+div.document td{
+padding:3px 7px 3px 7px;
+border:1px solid #333333;
+text-align:center;
+color:inherit;
+background-color:#FCFCFC;
+}
+
+div.footer{
+margin:50px auto 30px auto;
+text-align:center;
+font-size:85%;
+}
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
new file mode 100644
index 000000000..48ef60683
--- /dev/null
+++ b/host/docs/usrp2.rst
@@ -0,0 +1,128 @@
+========================================================================
+UHD - USRP2 App Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+Building firmware and FPGA images
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^
+FPGA Image
+^^^^^^^^^^^^^^^^^^
+Xilinx ISE 10.1 is required to build the FPGA image for the USRP2
+(newer version of ISE are known to build buggy images).
+The build requires that you have a unix-like environment with make.
+Make sure that xtclsh from the Xilinx ISE bin directory is in your $PATH.
+
+Run the following commands:
+::
+
+    cd <uhd-repo-path>/fpga/usrp2/top/u2_rev3
+    make bin
+
+*The image file will be ./build/u2_rev3.bin*
+
+^^^^^^^^^^^^^^^^^^
+Firmware Image
+^^^^^^^^^^^^^^^^^^
+The Microblaze GCC compiler from the Xilinx EDK is required to build the firmware.
+The build requires that you have a unix-like environment with autotools and make.
+Make sure that mb-gcc from the Xilinx EDK/microblaze directory is in your $PATH.
+
+Run the following commands:
+::
+
+    cd <uhd-repo-path>/firmware/microblaze
+    ./boostrap
+    ./configure host=mb
+    make
+
+*The image file will be ./apps/txrx.bin*
+
+------------------------------------------------------------------------
+Load the images onto the SD card
+------------------------------------------------------------------------
+**Warning!**
+Use the u2_flash_tool with caution. If you specify the wrong device node,
+you could overwrite your hard drive. Make sure that --dev= specifies the SD card.
+
+Load the FPGA image:
+
+::
+
+    cd <uhd-repo-path>/firmware/microblaze
+    sudo ./u2_flash_tool --dev=/dev/sd<XXX> -t fpga -w <path_to_fpga_image>
+
+Load the firmware image:
+
+::
+
+    cd <uhd-repo-path>/firmware/microblaze directory
+    sudo ./u2_flash_tool --dev=/dev/sd<XXX> -t s/w -w <path_to_firmware_image>
+
+------------------------------------------------------------------------
+Setup networking
+------------------------------------------------------------------------
+The USRP2 only supports gigabit ethernet, and
+will not work with a 10/100 Mbps interface.
+Because the USRP2 uses gigabit ethernet pause frames for flow control,
+you cannot use multiple USRP2s with a switch or a hub.
+It is recommended that each USRP2 be plugged directly into its own
+dedicated gigabit ethernet interface on the host computer.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setup the host interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The USRP2 communicates at the IP/UDP layer over the gigabit ethernet.
+The default IP address of the USRP2 is **192.168.10.2**
+You will need to configure the host's ethernet interface with a static IP address to enable communication.
+An address of **192.168.10.1** is recommended.
+
+**Note:**
+When using the UHD, if an IP address for the USRP2 is not specified,
+the software will use UDP broadcast packets to locate the USRP2.
+On some systems, the firewall will block UDP broadcast packets.
+It is recommended that you change or disable your firewall settings. 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Change the USRP2's IP address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You may need to change the USRP2's IP address for several reasons:
+
+* to satisfy your particular network configuration
+* to use multiple USRP2s on the same host computer
+* to set a known IP address into USRP2 (in case you forgot)
+
+**Method 1:**
+To change the USRP2's IP address
+you must know the current address of the USRP2,
+and the network must be setup properly as described above.
+Run the following commands:
+::
+
+    cd <prefix>/share/uhd/utils
+    ./usrp_burner --addr=192.168.10.2 --new-ip=192.168.10.3
+
+**Method 2 (Linux Only):**
+This method assumes that you do not know the IP address of your USRP2.
+It uses raw ethernet packets to bypass the IP/UDP layer to communicate with the USRP2.
+Run the following commands:
+::
+
+    cd <prefix>/share/uhd/utils
+    ./usrp2 recovery.py --ifc=eth0 --new-ip=192.168.10.3
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Debugging networking problems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Monitor the USRP2:**
+You can read the serial port on the rear of the USRP2
+to get debug verbose from the embedded microcontroller.
+Use a standard USB to tty-level serial converter at 230400 baud.
+The microcontroller prints useful information about IP addresses,
+MAC addresses, control packets, and fast-path settings.
+
+**Monitor the host network traffic:**
+Use wireshark to monitor packets send to and received from the USRP2.
diff --git a/host/lib/CMakeLists.txt b/host/lib/CMakeLists.txt
index b9e525bad..3a9ac1b08 100644
--- a/host/lib/CMakeLists.txt
+++ b/host/lib/CMakeLists.txt
@@ -69,7 +69,7 @@ MACRO(UHD_PYTHON_GEN_SOURCE_FILE pyfile outfile)
     ADD_CUSTOM_COMMAND(
         OUTPUT ${outfile} DEPENDS ${pyfile}
         COMMAND ${PYTHON_EXECUTABLE} ${pyfile} ${outfile}
-        COMMENT "Calling ${pyfile} to generate ${outfile}"
+        COMMENT "Generating ${outfile}"
     )
     LIST(APPEND libuhd_sources ${outfile})
 ENDMACRO(UHD_PYTHON_GEN_SOURCE_FILE)