Merge pull request #3 in PROC_LIBS/dsplib from CATREQ-2702 to master
[ep-processor-libraries/dsplib.git] / ti / dsplib / docs / bundle / doxygen / doxygen.h
1 /* ======================================================================== *
2  * DSPLIB -- TI Digital Signal Processing Library                          *
3  *                                                                          *
4  *   Doxygen generation header file                                         *
5  *                                                                          *
6  * Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/   *
7  *                                                                          *
8  *                                                                          *
9  *  Redistribution and use in source and binary forms, with or without      *
10  *  modification, are permitted provided that the following conditions      *
11  *  are met:                                                                *
12  *                                                                          *
13  *    Redistributions of source code must retain the above copyright        *
14  *    notice, this list of conditions and the following disclaimer.         *
15  *                                                                          *
16  *    Redistributions in binary form must reproduce the above copyright     *
17  *    notice, this list of conditions and the following disclaimer in the   *
18  *    documentation and/or other materials provided with the                *
19  *    distribution.                                                         *
20  *                                                                          *
21  *    Neither the name of Texas Instruments Incorporated nor the names of   *
22  *    its contributors may be used to endorse or promote products derived   *
23  *    from this software without specific prior written permission.         *
24  *                                                                          *
25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS     *
26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT       *
27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR   *
28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT    *
29  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
30  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT        *
31  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,   *
32  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY   *
33  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT     *
34  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE   *
35  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.    *
36  * ======================================================================== */
38 /**
39  * @mainpage  @PACKAGE User's Manual (@TARGETN)
40  *
41  *  @HLINE
42  *
43  *  <div>
44  *    <p>&nbsp;</p>
45  *    @section start Getting Started
46  *    <table @TSTYLE>
47  *      <tr>
48  *        <td><a @ASTYLE href="intro.html">Introduction</a></td>
49  *        <td>@PACKAGE features and advantages</td>
50  *      </tr>
51  *      <tr>
52  *        <td><a @ASTYLE href="install.html">Package Contents</a></td>
53  *        <td>What the installation provides and where</td>
54  *      </tr>
55  *      <tr>
56  *        <td><a @ASTYLE href="building.html">Building</a></td>
57  *        <td>How to build @PACKAGE using CCS Projects or GNU make</td>
58  *      </tr>
59  *      <tr>
60  *        <td><a @ASTYLE href="integrate.html">Integration</a></td>
61  *        <td>How to integrate @PACKAGE into your code</td>
62  *      </tr>
63  *      <tr>
64  *        <td><a @ASTYLE href="examples.html">Examples</a></td>
65  *        <td>Example projects provided with @PACKAGE </td>
66  *      </tr>
67  *      <tr>
68  *        <td @CSTYLE><a @ASTYLE target="_blank" href="@PKGMODLINK">API Reference</a></td>
69  *        <td>Detailed usage for all @PACKAGE kernels</td>
70  *      </tr>
71  *    </table>
72  *  </div>
73  *
74  *
75  *  <div>
76  *    <p>&nbsp;</p>
77  *    @section dox Additional Documents
78  *    <table @TSTYLE>
79  *      <tr>
80  *        <td @CSTYLE><a @ASTYLE @BLANK href="../../../@PKGRELNOTES">Release Notes</a></td>
81  *        <td>New features, device support, known issues, etc.</td>
82  *      </tr>
83  *      <tr>
84  *        <td><a @ASTYLE @BLANK href="../../@PKGSWMFEST">Software Manifest</a></td>
85  *        <td>Link to manifests for all packages in delivery</td>
86  *      </tr>
87  *      <tr>
88  *        <td><a @ASTYLE @BLANK href="../../@PKGTESTREP">Cycle Benchmarks</a></td>
89  *        <td>Cycle and memory benchmarking</td>
90  *      </tr>
91  *    </table>
92  *  </div>
93  *
94  *
95  *  <div>
96  *    <p>&nbsp;</p>
97  *    @section linx Helpful Links
98  *    <table @TSTYLE>
99  *      <tr>
100  *        <td @CSTYLE><a @ASTYLE @BLANK href="https://www-a.ti.com/downloads/sds_support/TICodegenerationTools/download.htm">Code Gen Tools</a></td>
101  *        <td>Download site for TI DSP code generation tools</td>
102  *      </tr>
103  *      <tr>
104  *        <td><a @ASTYLE @BLANK href="http://processors.wiki.ti.com/index.php/Download_CCS">Code Composer Studio</a></td>
105  *        <td>Download site for Code Composer Studio IDE Version 4.2 and 5.0</td>
106  *      </tr>
107  *      <tr>
108  *        <td><a @ASTYLE @BLANK href="http://e2e.ti.com/support/embedded/f/355.aspx">TI-RTOS  E2E Forum</a></td>
109  *        <td>Forum for @PACKAGE questions or remarks</td>
110  *      </tr>
111  *      <tr>
112  *        <td><a @ASTYLE @BLANK href="http://processors.wiki.ti.com/index.php/Software_libraries">Library Wiki</a></td>
113  *        <td>Find and download the latest DSPLIB release</td>
114  *      </tr>
115  *    </table>
116  *  </div>
117  * 
118  *  @SPACER
119  */
121 /**
122  * @page intro  Introduction 
123  * 
124  * <table @NSTYLE><tr><td><a @ASTYLE href="index.html">Back</a></td></tr></table>
125  *
126  * The TI C6000 @PACKAGE is an optimized DSP Function Library for C programmers. It includes many
127  * C-callable, optimized, general-purpose signal-processing routines. These routines are typically 
128  * used in computationally-intensive real-time applications where optimal execution speed is critical.
129  * By using these routines, you can achieve execution speeds considerably faster than equivalent code
130  * written in standard ANSI C language. In addition, by providing ready-to-use DSP functions, TI @PACKAGE 
131  * can significantly shorten your DSP application development time.
132  *
133  * @SPACER
134  *
135  * @section features  Features and Benefits
136  *  @SECSTART 
137  *  The TI @TARGETN @PACKAGE contains commonly used digital signal processing routines, 
138  *  as well as source code that allows you to modify functions to match your 
139  *  specific needs.
140  *
141  *  - ANSI C source code models
142  *  - C-callable routines fully compatible with the TI C6000 compiler
143  *  - Host library to enable PC based development and testing
144  *  - CCS V5 projects to rebuild library or individual routines unit test.
145  *  - <a @BLANK href="../../@PKGTESTREP">Benchmarks</a>
146  *  - Tested against reference C model
147  *  - Unit-test for each routines.
148  *  @SECEND
149  *
150  * @section routines  Software Routines
151  *  @SECSTART 
152  *  The rich set of software routines included in @PACKAGE are organized into 
153  *  seven functional categories:
154  *  
155  *  -# <a href="./dsplib_html/group___a_d_a_p_t_i_v_e_f_i_l_t_e_r.html">Adaptive filtering</a>
156  *  -# <a href="./dsplib_html/group___c_o_r_r_e_l_a_t_i_o_n.html">Correlation</a>
157  *  -# <a href="./dsplib_html/group___f_f_t.html">Fast Fourier Transform</a>
158  *  -# <a href="./dsplib_html/group___f_i_l_t_c_o_n_v.html">Filtering and convolution</a>
159  *  -# <a href="./dsplib_html/group___m_a_t_h.html">Math</a>
160  *  -# <a href="./dsplib_html/group___m_a_t_r_i_x.html">Matrix</a>
161  *  -# <a href="./dsplib_html/group___m_i_s_c.html">Miscellaneous</a>
162  *  @SECEND
163  *  
164  */
167 /**
168  * @page install  Package Contents
169  * 
170  * <table @NSTYLE><tr><td><a @ASTYLE href="index.html">Back</a></td></tr></table>
171  *
172  *  Unless otherwise specified, the @PACKAGE package installs under
173  *  <tt>C:\\ti\\</tt> in directory <tt> @PKGDIR</tt>.  
174  *  The directory structure of the installed package will look similar to that 
175  *  displayed below in Figure 1, though the install folder will match the installation
176  *  version.   
177  *  
178  *  <table rules="none" frame="void" cellspacing="0" cellpadding="0">
179  * @if C66 
180  *    <tr><td>
181  *      @image html dsplib_c66_directory.jpg "Figure 1. @TARGETN @PACKAGE Directory Structure"
182  *    </td></tr>
183  * @elseif C64P
184  *    <tr><td>
185  *      @image html dsplib_c64P_directory.jpg "Figure 1. @TARGETN @PACKAGE Directory Structure"
186  *    </td></tr>
187  * @elseif C674
188  *    <tr><td>
189  *      @image html dsplib_c674_directory.jpg "Figure 1. @TARGETN @PACKAGE Directory Structure"
190  *    </td></tr>
191  * @else
192  *    <tr><td>
193  *      <b>ERROR:  UNRECOGNIZED TARGET</b>
194  *    </td></tr>
195  * @endif
196  *  </table>
197  *
198  *  The files that comprise the @PACKAGE installation can be categorized into the 
199  *  following five categories.  
200  *
201  *    -# Documentation
202  *    -# Component Repository
203  *    -# Kernel Source
204  *    -# Eclipse Support
205  *    -# Internal Meta Data
206  *
207  *  The sections that follow provide details for each category.
208  *
209  * @SPACER
210  *  
211  * @section documents Documentation
212  *  @SECSTART 
213  *  Installation places all @PACKAGE documentation in a @c @b Docs directory in the 
214  *  @PACKAGE root.  The following documentation comes with the delivery:
215  *  
216  *  - @PKGMANCHM (this document, CHM format)
217  *  - @PKGMANHTML (this document, HTML format)
218  *  - <a @BLANK href="../../../@PKGRELNOTES">Release Notes</a>
219  *  - <a @BLANK href="../../@PKGSWMFEST">Software Manifest</a></td>
220  *  - <a @BLANK href="../../@PKGTESTREP">Cycle Benchmarks</a>
221  *  @SECEND
222  *
223  * @section repository  Component Repository
224  *  @SECSTART 
225  *  The installation creates a @c @b Components directory in the @PACKAGE root
226  *  folder.  This directory serves as a repository for all packages included
227  *  in the @PACKAGE installation.  Each package in this repository is compressed.
228  *  @SECEND
229  *
230  * @section kernelsrc  Kernel Source 
231  *  @SECSTART 
232  *  The installation also creates a @c @b Packages directory in the @PACKAGE root
233  *  folder.  This directory holds all kernels contained within the @PACKAGE 
234  *  library.  This directory follows the standard TI directory structure.  As an 
235  *  example, the files that comprise the @PACKAGE kernel @c @b @KERNELEX will be 
236  *  located, relative to the @PACKAGE root installation directory, at
237  *  <tt>packages/ti/@package/src/@KERNELEX/</tt>.  
238  *
239  *  Each Kernel is delivered with a CCSV5 project that illustrates 
240  *  the kernel API and performs several validation tests.  Each project provides
241  *  an estimate of kernel cycle and program memory requirements.
242  *  @SECEND
243  *
244  * @section eclipsedir  Eclipse Support
245  *  @SECSTART 
246  *  The @c @b Eclipse directory contains all files required for @PACKAGE to be 
247  *  recognized by Eclipse (Code Composer Studio) as a plug-in.  This is a support
248  *  directory and can be safely ignored.
249  *  @SECEND
250  *
251  * @section metadata  Internal Meta Data
252  *  @SECSTART 
253  *  The @PACKAGE installation creates a @c @b Package directory.  This directory 
254  *  contains meta information required by the TI packaging tools.  This is a 
255  *  support directory and can be safely ignored.  
256  *  @SECEND
257  *
258  */
261 /**
262  * @page examples  Examples 
263  * 
264  * <table @NSTYLE><tr><td><a @ASTYLE href="index.html">Back</a></td></tr></table>
265  *
266  *  The FFT example is provided in the examples folder. 
267  *  This example demonstrates the usage of the various FFT kernels provided with the @PACKAGE. 
268  *  The example shows:  
269  *
270  *   - Twiddle factor generation for the various kernels              
271  *   - Scaling that needs to be applied to get similar output when using different kernels                                   
272  *   - Demonstrates the usage of FFT APIs  
273  *
274  *   The examples folder contains an FFT CCS V5 project and a ReadMe.txt.
275  *
276  */
279 /**
280  * @page integrate  Integration
281  * 
282  * <table @NSTYLE><tr><td><a @ASTYLE href="index.html">Back</a></td></tr></table>
283  *
284  *  Since @PACKAGE is a collection of individual kernels, any combination of the 
285  *  kernels that comprise @PACKAGE may be integrated into a system individually.
286  *  Integration, for single or multiple kernels, requires four simple steps:
287  *
288  *    -# Compile @PACKAGE for @TARGETN (optional)
289  *    -# Add API calls within system code 
290  *    -# Compile system code
291  *    -# Link @PACKAGE 
292  *
293  *  The sections that follow provide details regarding the above four steps.
294  *
295  * @SPACER
296  *  
297  *  @section compile  Compile @PACKAGE for @TARGETN (optional)
298  *  @SECSTART 
299  *  On installation, the @PACKAGE libraries are built and ready to link.  Therefore,
300  *  this step is only required when the original kernel source code has been refined 
301  *  or contributions have been added.  See @ref building for details regarding 
302  *  re-building @PACKAGE .
303  *  @SECEND
304  *   
305  *  @section kernelcalls  Add @PACKAGE API Calls
306  *  @SECSTART 
307  *  Add calls to @PACKAGE kernels within the system source code as necessary.
308  *  Any system source file that contains calls to an @PACKAGE kernel will require 
309  *  that the @PACKAGE header file <tt> @PKGHEADER </tt> is included.  See the 
310  *  <a href="@PKGMANLINK">@PACKAGE Function Reference</a> for details on individual 
311  *  kernel APIs.
312  *  @SECEND
313  *
314  *  @section syscompile  System Compilation
315  *  @SECSTART 
316  *  To re-compile the system code, the path to the <tt>packages</tt> directory will 
317  *  need to be added to the compiler's include path search list.  This path will
318  *  depend on the @PACKAGE root installation directory.  This allows the main 
319  *  @PACKAGE header file to be moved from within the installation directory and 
320  *  still recognize the individual kernel headers.
321  *  @SECEND
322  *
323  *  @section linking  Linking @PACKAGE
324  *  @SECSTART 
325  *  The path to the @PACKAGE libraries must be provided to the linker via: <br>
326  *  -l <DSPLIB_INSTALL_DIR>/packages/ti/dsplib/lib/dsplib.lib 
327  *  @SECEND
328  *
329  */
332 /**
333  * @page building  @PACKAGE Build Process
334  * 
335  * <table @NSTYLE><tr><td><a @ASTYLE href="index.html">Back</a></td></tr></table>
336  *
337  *  @PACKAGE is provided with two methods for re-building libraries.  For those
338  *  familiar with TI's Code Composer Studio (Eclipse-based) IDE, we provide project
339  *  for rebuilding library with relative ease.  Likewise, many
340  *  developers are more comfortable with the GNU Make utility.  As such, we also
341  *  provide Makefiles to re-build the @PACKAGE library.
342  *
343  * @SPACER
344  *
345  * @section ccs_howto  Code Composer Studio
346  *  @SECSTART 
347  *  This release of @PACKAGE provides Code Composer Studio (CCS) Version 5 project 
348  *  to re-build library.  This project is located in the @c @b packages/ti/@package/lib folder. 
349  *
350  *  Follow the instructions at @ref ccs_build for more details.
351  *  @SECEND
352  *  
353  * @section gnu_howto  GNU Makefile
354  *  @SECSTART 
355  *  A GNU @b makefile is provided for rebuilding @PACKAGE via the GNU make utility.  
356  *  This file is located in the @c @b packages/ti/@package folder. The makefile provides 
357  *  a list of all tools, common build utilities and build rules required for re-building @PACKAGE binary. 
358  *
359  *  Follow the instructions at @ref gnu_build for more details.
360  *  @SECEND
361  *  
362  */
364 /** 
365  * @page ccs_build  CCS Build Process
366  * 
367  * <table @NSTYLE><tr><td><a @ASTYLE href="building.html">Back</a></td></tr></table>
368  *
369  *  To build any specific kernel for test, benchmarking or to pull in source code changes -
370  *  just locate the associated project file, load it and run within the CCS environment.
371  *  The sections below provide all necessary details to get started.
372  *  
373  *    -# Required Tools
374  *    -# Re-build @PACKAGE Library
375  *    -# Build Individual @PACKAGE Kernel
376  *
377  *  The sections that follow detail each item above.
378  *
379  * @SPACER
380  *
381  * @section ccs_tools  Required Tools
382  *  @SECSTART 
383  *  The following tools are required to build @PACKAGE using CCS (links provided).
384  *  Download and install all tools to a single local (@c @b C:) directory, 
385  *  for example, <tt><b>c:\\ti</b></tt>.
386  *
387  *  - <a target=_blank href="https://www-a.ti.com/downloads/sds_support/TICodegenerationTools/download.htm">Code Generation Tools</a>
388  *  - <a target=_blank href="http://processors.wiki.ti.com/index.php/Download_CCS">Code Composer Studio</a>
389  *
390  *  @note  A "My.TI" account is required for download and can be registered at <a target=_blank href="http://my.ti.com">my.ti.com</a>
391  *  @SECEND
392  *
393  * @section ccs_compile_all  @PACKAGE Build Procedure 
394  *  @SECSTART
395  *  
396  * The @PACKAGE package supports CCSV5.2 & above. The @PACKAGE may be build following the procedure below:
397  *
398  *   -# Open the CCSv5 application
399  *   -# Import the @PACKAGE @b makefile based project 
400  *     - Open the @b Project menu
401  *     - Select <b>Import Existing Eclipse Project</b>
402  *     - Import from the @PACKAGE @c @b packages/ti/@package/lib directory
403  *   -# Build the project
404  *     - Select <b>Rebuild Active Project</b> from @b Project menu 
405  *  
406  *  @SECEND
407  *
408  * @section ccs_compile_knl  Individual Kernel Build Procedure 
409  *  @SECSTART 
410  *  Any individual kernel within @PACKAGE may be compiled and tested via CCS following 
411  *  the procedure below:
412  *
413  *   -# Open the CCSV5 application
414  *   -# Import the @PACKAGE kernel project 
415  *     - Open the @b Project menu
416  *     - Select <b>Import Existing Eclipse Project</b>
417  *     - Import from the @PACKAGE @c @b /packages/ti/@package/src/\<kernel\> directory
418  *   -# Use the @b Debug/Release profile for debugging/modifing/optimizing kernels
419  *     - Open the @b Project menu
420  *     - Select <b>Active Build Configuration</b> and set to @b Debug/Release
421  *   -# Build and test the project
422  *     - Select <b>Rebuild Active Project</b> from @b Project menu 
423  *     - Test using the proper target configuration
424  *
425  *  @SECEND
426  *  
427  */
430 /** 
431  * @page gnu_build  GNU Make Build Process
432  * 
433  * <table @NSTYLE><tr><td><a @ASTYLE href="building.html">Back</a></td></tr></table>
434  *
435  *  A GNU @b makefile is also provided for rebuilding @PACKAGE via the GNU make utility.  
436  *  This file is located in the @c @b packages/ti/@package folder. The makefile provides 
437  *  a list of all tools, common build utilities and build rules required for generating 
438  *  @PACKAGE binary. 
439  *
440  *  -# Required Tools
441  *  -# Re-build @PACKAGE Library
442  *
443  *  The sections that follow detail each item above.
444  *
445  * @SPACER
446  *
447  * @section gnu_tools  Required Tools
448  *  @SECSTART 
449  *  The following tools are required to build @PACKAGE using GNU make (links provided).
450  *  Download and install all tools to a single local (@c @b C:) directory, 
451  *  for example, <tt><b>c:\\ti</b></tt>.
452  *
453  *  - <a target=_blank href="https://www-a.ti.com/downloads/sds_support/TICodegenerationTools/download.htm">Code Generation Tools</a>
454  *  - GNU Make (External Tool)
455  *
456  *  @note  A "My.TI" account is required for download and can be registered at <a target=_blank href="http://my.ti.com">my.ti.com</a>
457  *  @SECEND
458  * 
459  * 
460  * @section gnu_compile_all  @PACKAGE Build Procedure 
461  *  @SECSTART 
462  *  The @PACKAGE may be compiled using GNU make following the procedure below.  
463  *  Note that the first three items are followed by two options, either of which 
464  *  may be used to accomplish the goal.
465  *
466  *   -# Add @b cygwin/bin to the environment PATH (Windows only)
467  *   -# Correct the @b C6x_GEN_INSTALL_DIR path in the @b makefile (two options)
468  *     - Directly modify the makefile  OR
469  *     - Set the @b C6x_GEN_INSTALL_DIR in the environment with the proper tools path  
470  *   -# Build the library
471  *     - Enter <b><tt>make all</tt></b> to build the library 
472  *     - Enter <b><tt>make clean</tt></b> to clean all generated object files and artifacts
473  *  @SECEND
474  *
475  */