From 8740197dfed997bb235b73ec649edb803d544326 Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Wed, 18 Aug 2010 13:42:47 -0700 Subject: uhd: docs on building and installing images --- host/docs/CMakeLists.txt | 1 + host/docs/images.rst | 104 +++++++++++++++++++++++++++++++++++++++++++++++ host/docs/index.rst | 1 + host/docs/usrp2.rst | 36 ---------------- 4 files changed, 106 insertions(+), 36 deletions(-) create mode 100644 host/docs/images.rst (limited to 'host/docs') diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt index d0041f71c..b4383f88d 100644 --- a/host/docs/CMakeLists.txt +++ b/host/docs/CMakeLists.txt @@ -24,6 +24,7 @@ SET(manual_sources coding.rst dboards.rst general.rst + images.rst usrp2.rst ) diff --git a/host/docs/images.rst b/host/docs/images.rst new file mode 100644 index 000000000..ff5c5404e --- /dev/null +++ b/host/docs/images.rst @@ -0,0 +1,104 @@ +======================================================================== +UHD - Firmware and FPGA Image Application Notes +======================================================================== + +.. contents:: Table of Contents + +------------------------------------------------------------------------ +Images Overview +------------------------------------------------------------------------ +Every USRP device must be loaded with special firmware and FPGA images. +The methods of loading images into the device varies among devices: + +* **USRP1:** The host code will automatically load the firmware and FPGA at runtime. +* **USRP2:** The user must manually write the images onto the USRP2 SD card. + +------------------------------------------------------------------------ +Pre-built images +------------------------------------------------------------------------ + +Pre-built images are available for download. +See the UHD wiki for the download link. + +The pre-built images come in platform-specific installer packages +and platform-independent archive files: + +* **Linux:** DEB or RPM installer +* **Windows:** not available yet... +* **Macintosh:** not available yet... +* **Platform-independent:** ZIP or TAR.GZ archive + +^^^^^^^^^^^^^^^^^^ +Linux installers +^^^^^^^^^^^^^^^^^^ +The Linux-based installers will install the images into /usr/share/uhd/images. +On a Linux system, the UHD will always search this path for image files. + +Commands to install a linux rpm or deb package: + +:: + + sudo rpm -i .rpm + + -- OR -- + + sudo dpkg -i .deb + +^^^^^^^^^^^^^^^^^^^^^^ +Archive install +^^^^^^^^^^^^^^^^^^^^^^ +When installing images from an archive, there are two options: + +**Option 1:** + +Unpack the archive into the UHD installation prefix. +The UHD will always search /share/uhd/images for image files. +Where was set by the CMAKE_INSTALL_PREFIX at configure-time. + +**Option 2:** + +Unpack the archive anywhere and set the UHD_IMAGE_PATH environment variable. +The UHD_IMAGE_PATH may contain a list of directories to search for image files, +or paths to specific image files. + +------------------------------------------------------------------------ +Building images +------------------------------------------------------------------------ + +The UHD source repository comes with the source code necessary to build +both firmware and FPGA images for all supported devices. +The build commands for a particular image can be found in /images/Makefile. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Xilinx FPGA builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Xilinx ISE 12.x and up is required to build the Xilinx FPGA 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. + +See /fpga/usrp2/top/* + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Microblaze firmware builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The Microblaze GCC compiler from the Xilinx EDK is required to build the Microblaze firmware images. +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. + +See /firmware/microblaze + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Altera FPGA builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Quartus is required to build the Altera FPGA images. +Pre-built images can also be found in /fpga/usrp1/rbf + +See /fpga/usrp1/toplevel/* + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +FX2 firmware builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The sdcc compiler is required to build the FX2 firmware images. +The build requires that you have a unix-like environment with autotools and make. + +See /firmware/fx2 diff --git a/host/docs/index.rst b/host/docs/index.rst index b31a3d0ac..6973ede19 100644 --- a/host/docs/index.rst +++ b/host/docs/index.rst @@ -21,6 +21,7 @@ Building the UHD Application Notes ^^^^^^^^^^^^^^^^^^^^^ * `General App Notes <./general.html>`_ +* `Firmware and FPGA Image Notes <./images.html>`_ * `USRP2 App Notes <./usrp2.html>`_ * `Daughterboard App Notes <./dboards.html>`_ diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst index bc4ea0e44..3ac326f58 100644 --- a/host/docs/usrp2.rst +++ b/host/docs/usrp2.rst @@ -4,42 +4,6 @@ UHD - USRP2 Application Notes .. contents:: Table of Contents ------------------------------------------------------------------------- -Building firmware and FPGA images ------------------------------------------------------------------------- - -^^^^^^^^^^^^^^^^^^ -FPGA Image -^^^^^^^^^^^^^^^^^^ -Xilinx ISE 10.1 and up is required to build the FPGA image for the USRP2. -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 /fpga/usrp2/top/u2_rev3 - make -f Makefile.udp 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 /firmware/microblaze - ./boostrap - ./configure --host=mb - make - -*The image file will be ./usrp2/usrp2_txrx_uhd.bin* - ------------------------------------------------------------------------ Load the images onto the SD card ------------------------------------------------------------------------ -- cgit v1.2.3 From d99e22971975e9b5bfb966741684963be8f049f6 Mon Sep 17 00:00:00 2001 From: Josh Blum Date: Thu, 19 Aug 2010 17:10:16 -0700 Subject: uhd: added image utils code to search the images paths for image files --- host/docs/coding.rst | 7 +++++- host/docs/images.rst | 3 +-- host/include/uhd/utils/CMakeLists.txt | 1 + host/include/uhd/utils/images.hpp | 38 +++++++++++++++++++++++++++++++++ host/lib/utils/CMakeLists.txt | 1 + host/lib/utils/images.cpp | 40 +++++++++++++++++++++++++++++++++++ host/lib/utils/paths.cpp | 14 ------------ 7 files changed, 87 insertions(+), 17 deletions(-) create mode 100644 host/include/uhd/utils/images.hpp create mode 100644 host/lib/utils/images.cpp (limited to 'host/docs') diff --git a/host/docs/coding.rst b/host/docs/coding.rst index 84f9abf3e..23f350b0f 100644 --- a/host/docs/coding.rst +++ b/host/docs/coding.rst @@ -64,7 +64,12 @@ Integrating custom hardware ------------------------------------------------------------------------ Creators of custom hardware can create drivers that use the UHD API. These drivers can be built as dynamically loadable modules that the UHD will load at runtime. -For a module to be loaded at runtime, it must be found in the UHD_MODULE_PATH environment variable. + +For a module to be loaded at runtime, it must be: + +* found in the UHD_MODULE_PATH environment variable, +* installed into the /share/uhd/modules directory, +* or installed into /usr/share/uhd/modules directory (unix only). ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Custom motherboard diff --git a/host/docs/images.rst b/host/docs/images.rst index ff5c5404e..612a00aa5 100644 --- a/host/docs/images.rst +++ b/host/docs/images.rst @@ -58,8 +58,7 @@ Where was set by the CMAKE_INSTALL_PREFIX at configure-time. **Option 2:** Unpack the archive anywhere and set the UHD_IMAGE_PATH environment variable. -The UHD_IMAGE_PATH may contain a list of directories to search for image files, -or paths to specific image files. +The UHD_IMAGE_PATH may contain a list of directories to search for image files. ------------------------------------------------------------------------ Building images diff --git a/host/include/uhd/utils/CMakeLists.txt b/host/include/uhd/utils/CMakeLists.txt index ef8e64ce0..b39b6083c 100644 --- a/host/include/uhd/utils/CMakeLists.txt +++ b/host/include/uhd/utils/CMakeLists.txt @@ -23,6 +23,7 @@ INSTALL(FILES byteswap.ipp exception.hpp gain_group.hpp + images.hpp pimpl.hpp props.hpp safe_main.hpp diff --git a/host/include/uhd/utils/images.hpp b/host/include/uhd/utils/images.hpp new file mode 100644 index 000000000..8b5a1eedd --- /dev/null +++ b/host/include/uhd/utils/images.hpp @@ -0,0 +1,38 @@ +// +// 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 . +// + +#ifndef INCLUDED_UHD_UTILS_IMAGES_HPP +#define INCLUDED_UHD_UTILS_IMAGES_HPP + +#include +#include + +namespace uhd{ + + /*! + * Search for an image in the system image paths: + * Search compiled-in paths and environment variable paths + * for a specific image file with the provided file name. + * \param image_name the name of the file + * \return the full system path to the file + * \throw exception if the image was not found + */ + UHD_API std::string find_image_path(const std::string &image_name); + +} //namespace uhd + +#endif /* INCLUDED_UHD_UTILS_IMAGES_HPP */ diff --git a/host/lib/utils/CMakeLists.txt b/host/lib/utils/CMakeLists.txt index 68945545a..32b679d49 100644 --- a/host/lib/utils/CMakeLists.txt +++ b/host/lib/utils/CMakeLists.txt @@ -79,6 +79,7 @@ ENDIF(HAVE_DLFCN_H) LIBUHD_APPEND_SOURCES( ${CMAKE_SOURCE_DIR}/lib/utils/assert.cpp ${CMAKE_SOURCE_DIR}/lib/utils/gain_group.cpp + ${CMAKE_SOURCE_DIR}/lib/utils/images.cpp ${CMAKE_SOURCE_DIR}/lib/utils/load_modules.cpp ${CMAKE_SOURCE_DIR}/lib/utils/paths.cpp ${CMAKE_SOURCE_DIR}/lib/utils/props.cpp diff --git a/host/lib/utils/images.cpp b/host/lib/utils/images.cpp new file mode 100644 index 000000000..395e542c1 --- /dev/null +++ b/host/lib/utils/images.cpp @@ -0,0 +1,40 @@ +// +// 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 . +// + +#include +#include +#include +#include +#include + +namespace fs = boost::filesystem; + +std::vector get_image_paths(void); //defined in paths.cpp + +/*********************************************************************** + * Find a image in the image paths + **********************************************************************/ +std::string uhd::find_image_path(const std::string &image_name){ + if (fs::exists(image_name)){ + return fs::system_complete(image_name).file_string(); + } + BOOST_FOREACH(const fs::path &path, get_image_paths()){ + fs::path image_path = path / image_name; + if (fs::exists(image_path)) return image_path.file_string(); + } + throw std::runtime_error("Could not find path for image: " + image_name); +} diff --git a/host/lib/utils/paths.cpp b/host/lib/utils/paths.cpp index 6ad12d3cc..9e9525caf 100644 --- a/host/lib/utils/paths.cpp +++ b/host/lib/utils/paths.cpp @@ -85,17 +85,3 @@ std::vector get_module_paths(void){ paths.push_back(fs::path(INSTALLER_PKG_DATA_DIR) / "modules"); return paths; } - -/*********************************************************************** - * Find a image in the image paths - **********************************************************************/ -std::string find_image_path(const std::string &image_name){ - if (fs::exists(image_name)){ - return fs::system_complete(image_name).file_string(); - } - BOOST_FOREACH(const fs::path &path, get_image_paths()){ - fs::path image_path = path / image_name; - if (fs::exists(image_path)) return image_path.file_string(); - } - throw std::runtime_error("Could not find path for image: " + image_name); -} -- cgit v1.2.3