NAME

       volk_modtool - tailor VOLK modules

DESCRIPTION

       The  volk_modtool  tool is installed along with VOLK as a way of helping to construct, add
       to, and interogate the VOLK library or companion libraries.

       volk_modtool is installed into $prefix/bin.

       VOLK modtool enables creating standalone (out-of-tree) VOLK modules  and  provides  a  few
       tools  for  sharing VOLK kernels between VOLK modules.  If you need to design or work with
       VOLK kernels away from the canonical VOLK library, this is  the  tool.   If  you  need  to
       tailor your own VOLK library for whatever reason, this is the tool.

       The  canonical  VOLK  library  installs  a volk.h and a libvolk.so.  Your own library will
       install volk_$name.h and libvolk_$name.so.  Ya Gronk?  Good.

       There isn't a substantial difference between the canonical VOLK module and any other  VOLK
       module.  They're all peers.  Any module created via VOLK modtool will come complete with a
       default volk_modtool.cfg file associating the module with the base from which it came, its
       distinctive $name and its destination (or path).  These values (created from user input if
       VOLK modtool runs without a user-supplied config file or a default config file)  serve  as
       default  values for some VOLK modtool actions.  It's more or less intended for the user to
       change directories to the top level of a created VOLK module and then run volk_modtool  to
       take advantage of the values stored in the default volk_modtool.cfg file.

       Apart from creating new VOLK modules, VOLK modtool allows you to list the names of kernels
       in other modules, list the names of kernels  in  the  current  module,  add  kernels  from
       another  module into the current module, and remove kernels from the current module.  When
       moving kernels between modules, VOLK modtool does its best to keep the  qa  and  profiling
       code  for  those  kernels  intact.   If  the  base has a test or a profiling call for some
       kernel, those calls will follow the kernel when VOLK modtool adds that kernel.  If  QA  or
       profiling requires a puppet kernel, the puppet kernel will follow the original kernel when
       VOLK modtool adds that original kernel.  VOLK modtool respects puppets.

       ======================================================================

Installing a new VOLK Library:

       Run the command "volk_modtool -i". This will ask you three questions:

         name: // the name to give your VOLK library: volk_<name>
         destination: // directory new source tree is built under -- must exists.
                      // It will create <directory>/volk_<name>
         base: // the directory containing the original VOLK source code

       This will build a new skeleton  directory  in  the  destination  provided  with  the  name
       volk_<name>. It will contain the necessary structure to build:

         mkdir build
         cd build
         cmake -DCMAKE_INSTALL_PREFIX=/opt/volk ../
         make
         sudo make install

       Right now, the library is empty and contains no kernels. Kernels can be added from another
       VOLK library using the '-a' option. If not specified, the kernel will  be  extracted  from
       the  base  VOLK directory. Using the '-b' allows us to specify another VOLK library to use
       for this purpose.

         volk_modtool -a -n 32fc_x2_conjugate_dot_prod_32fc

       This     will      put      the      code      for      the      new      kernel      into
       <destination>/volk_<name>/kernels/volk_<name>/

       Other kernels must be added by hand. See the following webpages for more information about
       creating VOLK kernels:
         http://gnuradio.org/doc/doxygen/volk_guide.html
         http://gnuradio.org/redmine/projects/gnuradio/wiki/Volk

       ======================================================================

OPTIONS

       Options for Adding and Removing Kernels:
         -a, --add_kernel
              Add kernel from existing VOLK module. Uses the base VOLK module
              unless -b is used. Use -n to specify the kernel name.
              Requires: -n.
              Optional: -b

         -A, --add_all_kernels
              Add all kernels from existing VOLK module. Uses the base VOLK
              module unless -b is used.
              Optional: -b

         -x, --remove_kernel
              Remove kernel from module.
              Required: -n.
              Optional: -b

       Options for Listing Kernels:
         -l, --list
              Lists all kernels available in the base VOLK module.

         -k, --kernels
              Lists all kernels in this VOLK module.

         -r, --remote-list
              Lists all kernels in another VOLK module that is specified
              using the -b option.