5.2 Using the Fixed-Point Libraries

Building an application which utilizes the fixed-point libraries requires two types of files: header files and library files. Understanding fixed-point function naming conventions is needed for use.

Header Files

All standard C library entities are declared or defined in one or more standard headers. To make use of a library entity in a program, write an include directive that names the relevant standard header. The contents of a standard header are included by naming them in an include directive, as in:

#include <libq.h> /* include fixed-point library */

The standard headers can be included in any order. Do not include a standard header within a declaration. Do not define macros that have the same names as keywords before including a standard header.

A standard header never includes another standard header.

Library Files

The archived library files contain all the individual object files for each library function.

When linking an application, the library file (libq-elf.a or libq-dsp-elf.a) must be provided as an input to the linker (using the --library or -l linker option), such that the functions used by the application may be linked into the application. Also, linker options -lq and -lq-dsp must be used when linking the respective libraries.

A typical C application will require these library files: libc99-elf.a, libm-elf.a and libc99-pic30-elf.a. These libraries will be included automatically if linking is performed using the compiler.

Function Naming Conventions

Signed fixed-point types are defined as follows:

Qn_m

where:

• n is the number of data bits to the left of the radix point
• m is the number of data bits to the right of the radix point

For convenience, short names are also defined:

In this document, the terms Q15.16 and Q16 are used interchangeably; however, both imply Q15.16 format. Functions in the library are prefixed with the type of the return value. For example, _Q15acos returns a Q15 value equal to the arc cosine of its argument.

Argument types do not always match the return type. Refer to the function prototype for a specification of its arguments. In cases where the return value is not a fixed-point type, the argument type is appended to the function name. For example, function _itoaQ15 accepts a type Q15 argument.

In cases where two versions of a function are provided with the same return type but different argument types, the argument type is appended to the function name. For example: