diff options
| -rw-r--r-- | host/CMakeLists.txt | 21 | ||||
| -rw-r--r-- | host/README | 84 | ||||
| -rw-r--r-- | host/docs/CMakeLists.txt | 82 | ||||
| -rw-r--r-- | host/docs/Doxyfile.in (renamed from host/Doxyfile.in) | 0 | ||||
| -rw-r--r-- | host/docs/build.rst | 130 | ||||
| -rw-r--r-- | host/docs/index.rst | 28 | ||||
| -rw-r--r-- | host/docs/style.css | 102 | ||||
| -rw-r--r-- | host/docs/usrp2.rst | 128 | ||||
| -rw-r--r-- | host/lib/CMakeLists.txt | 2 |
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) |