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> </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> </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> </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 */