MLIB User's Guide DSP56800EX

Size: px

Start display at page:

Download "MLIB User's Guide DSP56800EX"

Kristin Powers
5 years ago
Views:

1 MLIB User's Guide DSP56800EX Document Number: DSP56800EXMLIBUG Rev. 2, 10/2015

2 2 Freescale Semiconductor, Inc.

3 Contents Section number Title Page Chapter 1 Library 1.1 Introduction Overview Data types API definition Supported compilers Special issues Library integration into project (CodeWarrior Development Studio) New project Library path variable Library folder addition Library path setup...20 Chapter 2 Algorithms in detail 2.1 MLIB_Abs Available versions Declaration Function use MLIB_AbsSat Available versions Declaration Function use MLIB_Add Available versions Declaration Function use...28 Freescale Semiconductor, Inc. 3

4 Section number Title Page 2.4 MLIB_AddSat Available versions Declaration Function use MLIB_Add Available versions Declaration Function use MLIB_Add4Sat Available versions Declaration Function use MLIB_Clb Available versions Declaration Function use MLIB_Conv Available versions Declaration Function use MLIB_Div Available versions Declaration Function use MLIB_DivSat Available versions Declaration Function use Freescale Semiconductor, Inc.

5 Section number Title Page 2.11 MLIB_Div1Q Available versions Declaration Function use MLIB_Div1QSat Available versions Declaration Function use MLIB_Log Available versions Declaration Function use MLIB_Mac Available versions Declaration Function use MLIB_MacSat Available versions Declaration Function use MLIB_MacRnd Available versions Declaration Function use MLIB_MacRndSat Available versions Declaration Function use...48 Freescale Semiconductor, Inc. 5

6 Section number Title Page 2.18 MLIB_Mac Available versions Declaration Function use MLIB_Mac4Sat Available versions Declaration Function use MLIB_Mac4Rnd Available versions Declaration Function use MLIB_Mac4RndSat Available versions Declaration Function use MLIB_Msu Available versions Declaration Function use MLIB_MsuSat Available versions Declaration Function use MLIB_MsuRnd Available versions Declaration Function use Freescale Semiconductor, Inc.

7 Section number Title Page 2.25 MLIB_MsuRndSat Available versions Declaration Function use MLIB_Msu Available versions Declaration Function use MLIB_Msu4Sat Available versions Declaration Function use MLIB_Msu4Rnd Available versions Declaration Function use MLIB_Msu4RndSat Available versions Declaration Function use MLIB_Mul Available versions Declaration Function use MLIB_MulSat Available versions Declaration Function use...68 Freescale Semiconductor, Inc. 7

8 Section number Title Page 2.32 MLIB_MulNeg Available versions Declaration Function use MLIB_MulNegSat Available versions Declaration Function use MLIB_MulRnd Available versions Declaration Function use MLIB_MulRndSat Available versions Declaration Function use MLIB_MulNegRnd Available versions Declaration Function use MLIB_MulNegRndSat Available versions Declaration Function use MLIB_Neg Available versions Declaration Function use Freescale Semiconductor, Inc.

9 Section number Title Page 2.39 MLIB_NegSat Available versions Declaration Function use MLIB_Rcp Available versions Declaration Function use MLIB_Rcp1Q Available versions Declaration Function use MLIB_Rnd Available versions Declaration Function use MLIB_RndSat Available versions Declaration Function use MLIB_Sat Available versions Declaration Function use MLIB_Sh1L Available versions Declaration Function use...87 Freescale Semiconductor, Inc. 9

10 Section number Title Page 2.46 MLIB_Sh1LSat Available versions Declaration Function use MLIB_Sh1R Available versions Declaration Function use MLIB_ShL Available versions Declaration Function use MLIB_ShLSat Available versions Declaration Function use MLIB_ShR Available versions Declaration Function use MLIB_ShLBi Available versions Declaration Function use MLIB_ShLBiSat Available versions Declaration Function use Freescale Semiconductor, Inc.

11 Section number Title Page 2.53 MLIB_ShRBi Available versions Declaration Function use MLIB_ShRBiSat Available versions Declaration Function use MLIB_Sign Available versions Declaration Function use MLIB_Sub Available versions Declaration Function use MLIB_SubSat Available versions Declaration Function use MLIB_Sub Available versions Declaration Function use MLIB_Sub4Sat Available versions Declaration Function use Freescale Semiconductor, Inc. 11

12 12 Freescale Semiconductor, Inc.

13 Chapter 1 Library 1.1 Introduction Overview This user's guide describes the Math Library (MLIB) for the family of DSP56800EX core-based digital signal controllers. This library contains optimized functions Data types MLIB supports several data types: (un)signed integer, fractional, and accumulator. The integer data types are useful for general-purpose computation; they are familiar to the MPU and MCU programmers. The fractional data types enable powerful numeric and digital-signal-processing algorithms to be implemented. The accumulator data type is a combination of both; that means it has the integer and fractional portions. The following list shows the integer types defined in the libraries: Unsigned 16-bit integer <0 ; 65535> with the minimum resolution of 1 Signed 16-bit integer < ; 32767> with the minimum resolution of 1 Unsigned 32-bit integer <0 ; > with the minimum resolution of 1 Signed 32-bit integer < ; > with the minimum resolution of 1 The following list shows the fractional types defined in the libraries: Fixed-point 16-bit fractional <-1 ; > with the minimum resolution of 2-15 Fixed-point 32-bit fractional <-1 ; > with the minimum resolution of 2-31 The following list shows the accumulator types defined in the libraries: Freescale Semiconductor, Inc. 13

14 Introduction Fixed-point 16-bit accumulator < ; > with the minimum resolution of 2-7 Fixed-point 32-bit accumulator < ; > with the minimum resolution of API definition MLIB uses the types mentioned in the previous section. To enable simple usage of the algorithms, their names use set prefixes and postfixes to distinguish the functions' versions. See the following example: f32result = MLIB_Mac_F32lss(f32Accum, f16mult1, f16mult2); where the function is compiled from four parts: MLIB this is the library prefix Mac the function name Multiply-Accumulate F32 the function output type lss the types of the function inputs; if all the inputs have the same type as the output, the inputs are not marked The input and output types are described in the following table: Table 1-1. Input/output types Type Output Input frac16_t F16 s frac32_t F32 l acc32_t A32 a Supported compilers MLIB for the DSP56800EX core is written in assembly language with C-callable interface. The library is built and tested using the following compilers: CodeWarrior Development Studio For the CodeWarrior Development Studio, the library is delivered in the mlib.lib file. The interfaces to the algorithms included in this library are combined into a single public interface include file, mlib.h. This is done to lower the number of files required to be included in your application. 14 Freescale Semiconductor, Inc.

15 Chapter 1 Library Special issues 1. The equations describing the algorithms are symbolic. If there is positive 1, the number is the closest number to 1 that the resolution of the used fractional type allows. If there are maximum or minimum values mentioned, check the range allowed by the type of the particular function version. 2. The library functions require the core saturation mode to be turned off, otherwise the results can be incorrect. Several specific library functions are immune to the setting of the saturation mode. 3. The library functions round the result (the API contains Rnd) to the nearest (two's complement rounding) or to the nearest even number (convergent round). The mode used depends on the core option mode register (OMR) setting. See the core manual for details. 4. All non-inline functions are implemented without storing any of the volatile registers (refer to the compiler manual) used by the respective routine. Only the non-volatile registers (C10, D10, R5) are saved by pushing the registers on the stack. Therefore, if the particular registers initialized before the library function call are to be used after the function call, it is necessary to save them manually. 1.2 Library integration into project (CodeWarrior Development Studio) This section provides a step-by-step guide to quickly and easily integrate the MLIB into an empty project using CodeWarrior Development Studio. This example uses the MC56F84789 part, and the default installation path (C:\Freescale\FSLESL \DSP56800EX_FSLESL_4.2) is supposed. If you have a different installation path, you must use that path instead New project To start working on an application, create a new project. If the project already exists and is open, skip to the next section. Follow the steps given below to create a new project. 1. Launch CodeWarrior Development Studio. 2. Choose File > New > Bareboard Project, so that the "New Bareboard Project" dialog appears. 3. Type a name of the project, for example, MyProject01. Freescale Semiconductor, Inc. 15

$\CWProjects\MyProject01, and click Next. See Figure 1-1. Figure 1-1. Project name and location 5. Expand the tree by clicking the 56800/E (DSC) and MC56F84789.$

16 Library integration into project (CodeWarrior Development Studio) 4. If you don't use the default location, untick the Use default location checkbox, and type the path where you want to create the project folder; for example, C: \CWProjects\MyProject01, and click Next. See Figure 1-1. Figure 1-1. Project name and location 5. Expand the tree by clicking the 56800/E (DSC) and MC56F Select the Application option and click Next. See Figure 1-2. Figure 1-2. Processor selection 6. Now select the connection that will be used to download and debug the application. In this case, select the option P&E USB MultiLink Universal[FX] / USB MultiLink and Freescale USB TAP, and click Next. See Figure Freescale Semiconductor, Inc.

Chapter 1 Library Figure 1-3. Connection selection 7.

See Figure 1-5. Figure 1-5. Project folder 1.2.

17 Chapter 1 Library Figure 1-3. Connection selection 7. From the options given, select the Simple Mixed Assembly and C language, and click Finish. See Figure 1-4. Figure 1-4. Language choice The new project is now visible in the left-hand part of CodeWarrior Development Studio. See Figure 1-5. Figure 1-5. Project folder Library path variable To make the library integration easier, create a variable that will hold the information about the library path. 1. Right-click the MyProject01 node in the left-hand part and click Properties, or select Project > Properties from the menu. The project properties dialog appears. Freescale Semiconductor, Inc. 17

Library integration into project (CodeWarrior Development Studio) 2. Expand the Resource node and click Linked Resources. See Figure 1-6. Figure 1-6. Project properties 3.

18 Library integration into project (CodeWarrior Development Studio) 2. Expand the Resource node and click Linked Resources. See Figure 1-6. Figure 1-6. Project properties 3. Click the 'New ' button on the right-hand side. 4. In the dialog that appears (see Figure 1-7), type this variable name into the Name box: FSLESL_LOC 5. Select the library parent folder by clicking 'Folder ' or just typing the following path into the Location box: C:\Freescale\FSLESL\DSP56800EX_FSLESL_4.2_CW and click OK. 6. Click OK in the previous dialog. 18 Freescale Semiconductor, Inc.

Chapter 1 Library Figure 1-7. New variable 1.2.3 Library folder addition To use the library, add it into the CodeWarrior Project tree dialog. 1. Right-click the MyProject01 node in the left-hand part and click New > Folder, or select File > New > Folder from the menu.

19 Chapter 1 Library Figure 1-7. New variable Library folder addition To use the library, add it into the CodeWarrior Project tree dialog. 1. Right-click the MyProject01 node in the left-hand part and click New > Folder, or select File > New > Folder from the menu. A dialog appears. 2. Click Advanced to show the advanced options. 3. To link the library source, select the third option Link to alternate location (Linked Folder). 4. Click Variables, and select the FSLESL_LOC variable in the dialog that appears, click OK, and/or type the variable name into the box. See Figure Click Finish, and you will see the library folder linked in the project. See Figure 1-9 Freescale Semiconductor, Inc. 19

Right-click the MyProject01 node in the left-hand part and click Properties, or select Project > Properties from the menu.

20 Library integration into project (CodeWarrior Development Studio) Figure 1-8. Folder link Figure 1-9. Projects libraries paths Library path setup 1. Right-click the MyProject01 node in the left-hand part and click Properties, or select Project > Properties from the menu. A dialog with the project properties appears. 2. Expand the C/C++ Build node, and click Settings. 3. In the right-hand tree, expand the DSC Linker node, and click Input. See Figure Freescale Semiconductor, Inc.

$Look for the FSLESL_LOC variable by clicking Variables, and then finish the path in the box by adding one of the following: $FSLESL_LOC\MLIB\mlib_SDM.$

21 Chapter 1 Library 4. In the third dialog Additional Libraries, click the 'Add ' icon, and a dialog appears. 5. Look for the FSLESL_LOC variable by clicking Variables, and then finish the path in the box by adding one of the following: $FSLESL_LOC\MLIB\mlib_SDM.lib for small data model projects $FSLESL_LOC\MLIB\mlib_LDM.lib for large data model projects 6. Tick the box Relative To, and select FSLESL_LOC next to the box. See Figure 1-9. Click OK. 7. Now, you will see the library added in the box. See Figure Figure Library file inclusion Freescale Semiconductor, Inc. 21

Library integration into project (CodeWarrior Development Studio) Figure 1-11. Linker setting 8. In the tree under the DSC Compiler node, click Access Paths.

$Look for the FSLESL_LOC variable by clicking Variables, and then finish the path in the box to be: $FSLESL_LOC\MLIB\include. 11.$

22 Library integration into project (CodeWarrior Development Studio) Figure Linker setting 8. In the tree under the DSC Compiler node, click Access Paths. 9. In the Search User Paths dialog (#include ), click the 'Add ' icon, and a dialog will appear. 10. Look for the FSLESL_LOC variable by clicking Variables, and then finish the path in the box to be: $FSLESL_LOC\MLIB\include. 11. Tick the box Relative To, and select FSLESL_LOC next to the box. See Figure Click OK. 12. Now you will see the path added in the box. See Figure Click OK. Figure Library include path addition 22 Freescale Semiconductor, Inc.

23 Chapter 1 Library Figure Compiler setting The final step is typing the #include syntax into the code. Include the library into the main.c file. In the left-hand dialog, open the Sources folder of the project, and doubleclick the main.c file. After the main.c file opens up, include the following line into the #include section: When you click the Build icon (hammer), the project will be compiled without errors. Freescale Semiconductor, Inc. 23

24 Library integration into project (CodeWarrior Development Studio) 24 Freescale Semiconductor, Inc.

25 Chapter 2 Algorithms in detail 2.1 MLIB_Abs The MLIB_Abs functions return the absolute value of the input. The function does not saturate the output. See the following equation: Equation 1. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may overflow. The available versions of the MLIB_Abs function are shown in the following table. Table 2-1. Function versions Function name Input type Result type Description MLIB_Abs_F16 frac16_t frac16_t Absolute value of a 16-bit fractional value. The output is within the range <-1 ; 1). MLIB_Abs_F32 frac32_t frac32_t Absolute value of a 32-bit fractional value. The output is within the range <-1 ; 1) Declaration The available MLIB_Abs functions have the following declarations: frac16_t MLIB_Abs_F16(frac16_t f16val) frac32_t MLIB_Abs_F32(frac32_t f32val) Freescale Semiconductor, Inc. 25

26 MLIB_AbsSat Function use The use of the MLIB_Abs function is shown in the following example: static frac32_t f32result; static frac32_t f32val; f32val = FRAC32(-0.354); /* f32val = */ /* f32result = f32val */ f32result = MLIB_Abs_F32(f32Val); 2.2 MLIB_AbsSat The MLIB_AbsSat functions return the absolute value of the input. The function saturates the output. See the following equation: Equation 2. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <0 ; 1). The result may saturate. The available versions of the MLIB_AbsSat function are shown in the following table. Table 2-2. Function versions Function name Input type Result type Description MLIB_AbsSat_F16 frac16_t frac16_t Absolute value of a 16-bit fractional value. The output is within the range <0 ; 1). MLIB_AbsSat_F32 frac32_t frac32_t Absolute value of a 32-bit fractional value. The output is within the range <0 ; 1). 26 Freescale Semiconductor, Inc.

27 Chapter 2 Algorithms in detail Declaration The available MLIB_AbsSat functions have the following declarations: frac16_t MLIB_AbsSat_F16(frac16_t f16val) frac32_t MLIB_AbsSat_F32(frac32_t f32val) Function use The use of the MLIB_AbsSat function is shown in the following example: static frac16_t f16val, f16result; f16val = FRAC16(-0.835); /* f16val = */ /* f16result = sat( f16val ) */ f16result = MLIB_AbsSat_F16(f16Val); 2.3 MLIB_Add The MLIB_Add functions return the sum of two addends. The function does not saturate the output. See the following equation: Equation 3. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may overflow. Freescale Semiconductor, Inc. 27

28 MLIB_Add Accumulator output with fractional inputs - the output is the accumulator type, where the result can be out of the range <-1 ; 1). The inputs are the fractional values only. Accumulator output with mixed inputs - the output is the accumulator type, where the result can be out of the range <-1 ; 1). The inputs are the accumulator and fractional values. The result may overflow. The available versions of the MLIB_Add function are shown in the following table. Function name Input type Result type Addend 1 Addend 2 Table 2-3. Function versions Description MLIB_Add_F16 frac16_t frac16_t frac16_t Addition of two 16-bit fractional addends. The output is within the range <-1 ; 1). MLIB_Add_F32 frac32_t frac32_t frac32_t Addition of two 32-bit fractional addends. The output is within the range <-1 ; 1). MLIB_Add_A32ss frac16_t frac16_t acc32_t Addition of two 16-bit fractional addends; the result is a 32- bit accumulator. The output may be out of the range <-1 ; 1). MLIB_Add_A32as acc32_t frac16_t acc32_t A 16-bit fractional addend is added to a 32-bit accumulator. The output may be out of the range <-1 ; 1) Declaration The available MLIB_Add functions have the following declarations: frac16_t MLIB_Add_F16(frac16_t f16add1, frac16_t f16add2) frac32_t MLIB_Add_F32(frac32_t f32add1, frac32_t f32add2) acc32_t MLIB_Add_A32ss(frac16_t f16add1, frac16_t f16add2) acc32_t MLIB_Add_A32as(acc32_t a32accum, frac16_t f16add) Function use The use of the MLIB_Add function is shown in the following example: static acc32_t a32result; static frac16_t f16add1, f16add2; f16add1 = FRAC16(-0.8); /* f16add1 = -0.8 */ f16add2 = FRAC16(-0.5); /* f16add2 = -0.5 */ /* a32result = f16add1 + f16add2 */ a32result = MLIB_Add_A32ss(f16Add1, f16add2); 28 Freescale Semiconductor, Inc.

29 Chapter 2 Algorithms in detail 2.4 MLIB_AddSat The MLIB_AddSat functions return the sum of two addends. The function saturates the output. See the following equation: Equation 4. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may saturate. The available versions of the MLIB_AddSat function are shown in the following table. Function name Input type Result type Addend 1 Addend 2 Table 2-4. Function versions Description MLIB_AddSat_F16 frac16_t frac16_t frac16_t Addition of two 16-bit fractional addends. The output is within the range <-1 ; 1). MLIB_AddSat_F32 frac32_t frac32_t frac32_t Addition of two 32-bit fractional addends. The output is within the range <-1 ; 1) Declaration The available MLIB_AddSat functions have the following declarations: frac16_t MLIB_Add_F16(frac16_t f16add1, frac16_t f16add2) frac32_t MLIB_Add_F32(frac32_t f32add1, frac32_t f32add2) Function use The use of the MLIB_AddSat function is shown in the following example: Freescale Semiconductor, Inc. 29

30 MLIB_Add4 static frac32_t f32add1, f32add2, f32result; f32add1 = FRAC32(-0.8); /* f32add1 = -0.8 */ f32add2 = FRAC32(-0.5); /* f32add2 = -0.5 */ /* f32result = sat(f32add1 + f32add2) */ f32result = MLIB_AddSat_F32(f32Add1, f32add2); 2.5 MLIB_Add4 The MLIB_Add4 functions return the sum of four addends. The function does not saturate the output. See the following equation: Equation 5. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may overflow. The available versions of the MLIB_Add4 function are shown in the following table. Table 2-5. Function versions Function name Input type Result type Add. 1 Add. 2 Add. 3 Add. 4 Description MLIB_Add4_F16 frac16_t frac16_t frac16_t frac16_t frac16_t Addition of four 16-bit fractional addends. The output is within the range <-1 ; 1). MLIB_Add4_F32 frac32_t frac32_t frac32_t frac32_t frac32_t Addition of four 32-bit fractional addends. The output is within the range <-1 ; 1) Declaration The available MLIB_Add4 functions have the following declarations: 30 Freescale Semiconductor, Inc.

31 Chapter 2 Algorithms in detail frac16_t MLIB_Add4_F16(frac16_t f16add1, frac16_t f16add2, frac16_t f16add3, frac16_t f16add4) frac32_t MLIB_Add4_F32(frac32_t f32add1, frac32_t f32add2, frac32_t f32add3, frac32_t f32add4) Function use The use of the MLIB_Add4 function is shown in the following example: static frac32_t f32result; static frac32_t f32add1, f32add2, f32add3, f32add4; f32add1 = FRAC32(-0.3); /* f32add1 = -0.3 */ f32add2 = FRAC32(0.5); /* f32add2 = 0.5 */ f32add3 = FRAC32(-0.2); /* f32add3 = -0.2 */ f32add4 = FRAC32(-0.4); /* f32add4 = -0.4 */ /* f32result = f32add1 + f32add2 + f32add3 + f32add4 */ f32result = MLIB_Add4_F32(f32Add1, f32add2, f32add3, f32add4); 2.6 MLIB_Add4Sat The MLIB_Add4Sat functions return the sum of four addends. The function saturates the output. See the following equation: Equation 6. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may saturate. Freescale Semiconductor, Inc. 31

32 MLIB_Clb The available versions of the MLIB_Add4Sat function are shown in the following table. Table 2-6. Function versions Function name Input type Result type Add. 1 Add. 2 Add. 3 Add. 4 Description MLIB_Add4Sat_F16 frac16_t frac16_t frac16_t frac16_t frac16_t Addition of four 16-bit fractional addends. The output is within the range <-1 ; 1). MLIB_Add4Sat_F32 frac32_t frac32_t frac32_t frac32_t frac32_t Addition of four 32-bit fractional addends. The output is within the range <-1 ; 1) Declaration The available MLIB_Add4Sat functions have the following declarations: frac16_t MLIB_Add4Sat_F16(frac16_t f16add1, frac16_t f16add2, frac16_t f16add3, frac16_t f16add4) frac32_t MLIB_Add4Sat_F32(frac32_t f32add1, frac32_t f32add2, frac32_t f32add3, frac32_t f32add4) Function use The use of the MLIB_Add4Sat function is shown in the following example: static frac16_t f16result, f16add1, f16add2, f16add3, f16add4; f16add1 = FRAC16(-0.7); /* f16add1 = -0.7 */ f16add2 = FRAC16(0.9); /* f16add2 = 0.9 */ f16add3 = FRAC16(0.4); /* f16add3 = 0.4 */ f16add4 = FRAC16(0.7); /* f16add4 = 0.7 */ /* f16result = sat(f16add1 + f16add2 + f16add3 + f16add4) */ f16result = MLIB_Add4Sat_F16(f16Add1, f16add2, f16add3, f16add4); 2.7 MLIB_Clb The MLIB_Clb functions return the number of leading bits of the input. If the input is 0, it returns the size of the type minus one. 32 Freescale Semiconductor, Inc.

33 Chapter 2 Algorithms in detail Available versions This function is available in the following versions: Integer output with fractional input - the output is the unsigned integer value when the input is fractional; the result is greater than or equal to 0. The available versions of the MLIB_Clb function are shown in the following table. Table 2-7. Function versions Function name Input type Result type Description MLIB_Clb_U16s frac16_t uint16_t Counts the leading bits of a 16-bit fractional value. The output is within the range <0 ; 15>. MLIB_Clb_U16l frac32_t uint16_t Counts the leading bits of a 32-bit fractional value. The output is within the range <0 ; 31> Declaration The available MLIB_Clb functions have the following declarations: uint16_t MLIB_Clb_U16s(frac16_t f16val) uint16_t MLIB_Clb_U16l(frac32_t f32val) Function use The use of the MLIB_Clb function is shown in the following example: static uint16_t u16result; static frac32_t f32val; f32val = FRAC32( ); /* f32val = */ /* u16result = clb(f32val) */ u16result = MLIB_Clb_U16l(f32Val); 2.8 MLIB_Conv Freescale Semiconductor, Inc. 33

34 MLIB_Conv The MLIB_Conv functions return the input value, converted to the output type Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The available versions of the MLIB_Conv function are shown in the following table. Table 2-8. Function versions Function name Input type Result type Description MLIB_Conv_F16l frac32_t frac16_t Conversion of a 32-bit fractional value to a 16-bit fractional value. The output is within the range <-1 ; 1). MLIB_Conv_F32s frac16_t frac32_t Conversion of a 16-bit fractional value to a 32-bit fractional value. The output is within the range <-1 ; 1) Declaration The available MLIB_Conv functions have the following declarations: frac16_t MLIB_Conv_F16l(frac32_t f32val) frac32_t MLIB_Conv_F32s(frac16_t f16val) Function use The use of the MLIB_Conv function is shown in the following example: static frac32_t f32result; static frac16_t f16val; f16val = FRAC16(-0.354); /* f16val = */ /* f32result = (frac32_t)f16val << 16 */ f32result = MLIB_Conv_F32s(f16Val); 34 Freescale Semiconductor, Inc.

35 Chapter 2 Algorithms in detail 2.9 MLIB_Div The MLIB_Div functions return the fractional division of the numerator and denominator. The function does not saturate the output. See the following equation: Equation 7. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The function is only defined for: nominator < denominator. The function returns undefined results out of this condition. Accumulator output - the output is the accumulator type, where the result may be out of the range <-1 ; 1). The available versions of the MLIB_Div function are shown in the following table: Function name Input type Result type Num. Denom. Table 2-9. Function versions Description MLIB_Div_F16 frac16_t frac16_t frac16_t Division of a 16-bit fractional numerator and denominator. The output is within the range <-1 ; 1). MLIB_Div_F16ls frac32_t frac16_t frac16_t Division of a 32-bit fractional numerator by a 16-bit fractional denominator; the output is a 16-bit fractional result. The output is within the range <-1 ; 1). MLIB_Div_F16ll frac32_t frac32_t frac16_t Division of a 32-bit fractional numerator and denominator; the output is a 16-bit fractional result. The output is within the range <-1 ; 1). MLIB_Div_F32ls frac32_t frac16_t frac32_t Division of a 32-bit fractional numerator by a 16-bit fractional denominator; the output is a 32-bit fractional result. The output is within the range <-1 ; 1). MLIB_Div_F32 frac32_t frac32_t frac32_t Division of a 32-bit fractional numerator and denominator. The output is within the range <-1 ; 1). MLIB_Div_A32ss frac16_t frac16_t acc32_t Division of a 16-bit fractional numerator and denominator; the output is a 32-bit accumulator result. The output may be out of the range <-1 ; 1). Table continues on the next page... Freescale Semiconductor, Inc. 35

36 MLIB_DivSat Table 2-9. Function versions (continued) Function name Input type Result type Num. Denom. Description MLIB_Div_A32ls frac32_t frac16_t acc32_t Division of a 32-bit fractional numerator by a 16-bit fractional denominator; the output is a 32-bit accumulator result. The output may be out of the range <-1 ; 1). MLIB_Div_A32ll frac32_t frac32_t acc32_t Division of a 32-bit fractional numerator and denominator; the output is a 32-bit accumulator result. The output may be out of the range <-1 ; 1). MLIB_Div_A32as acc32_t frac16_t acc32_t Division of a 32-bit accumulator numerator by a 16-bit fractional denominator; the output is a 32-bit accumulator result. The output may be out of the range <-1 ; 1) Declaration The available MLIB_Div functions have the following declarations: frac16_t MLIB_Div_F16(frac16_t f16num, frac16_t f16denom) frac16_t MLIB_Div_F16ls(frac32_t f32num, frac16_t f16denom) frac16_t MLIB_Div_F16ll(frac32_t f32num, frac32_t f32denom) frac32_t MLIB_Div_F32ls(frac32_t f32num, frac16_t f16denom) frac32_t MLIB_Div_F32(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_Div_A32ss(frac16_t f16num, frac16_t f16denom) acc32_t MLIB_Div_A32ls(frac32_t f32num, frac16_t f16denom) acc32_t MLIB_Div_A32ll(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_Div_A32as(acc32_t a32num, frac16_t f16denom) Function use The use of the MLIB_Div function is shown in the following example: static frac32_t f32num, f32result; static frac16_t f16denom; f32num = FRAC32(0.2); /* f32num = 0.2 */ f16denom = FRAC16(-0.495); /* f16denom = */ /* f32result = f32num / f16denom */ f32result = MLIB_Div_F32ls(f32Num, f16denom); 2.10 MLIB_DivSat 36 Freescale Semiconductor, Inc.

37 Chapter 2 Algorithms in detail The MLIB_DivSat functions return the fractional division of the numerator and denominator. The function saturates the output. See the following equation: Equation 8. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may saturate. Accumulator output - the output is the accumulator type, where the result may be out of the range <-1 ; 1). The available versions of the MLIB_DivSat function are shown in the following table: Function name Input type Result type Num. Denom. Table Function versions Description MLIB_DivSat_F16 frac16_t frac16_t frac16_t Division of a 16-bit fractional numerator and denominator. The output is within the range <-1 ; 1). MLIB_DivSat_F16ls frac32_t frac16_t frac16_t Division of a 32-bit fractional numerator by a 16-bit fractional denominator; the output is a 16-bit fractional result. The output is within the range <-1 ; 1). MLIB_DivSat_F16ll frac32_t frac32_t frac16_t Division of a 32-bit fractional numerator and denominator; the output is a 16-bit fractional result. The output is within the range <-1 ; 1). MLIB_DivSat_F32ls frac32_t frac16_t frac32_t Division of a 32-bit fractional numerator by a 16-bit fractional denominator; the output is a 32-bit fractional result. The output is within the range <-1 ; 1). MLIB_DivSat_F32 frac32_t frac32_t frac32_t Division of a 32-bit fractional numerator and denominator. The output is within the range <-1 ; 1). MLIB_DivSat_A32as acc32_t frac16_t acc32_t Division of a 32-bit accumulator numerator by a 16-bit fractional denominator; the output is a 32-bit accumulator result. The output may be out of the range <-1 ; 1) Declaration The available MLIB_DivSat functions have the following declarations: Freescale Semiconductor, Inc. 37

38 MLIB_Div1Q frac16_t MLIB_DivSat_F16(frac16_t f16num, frac16_t f16denom) frac16_t MLIB_DivSat_F16ls(frac32_t f32num, frac16_t f16denom) frac16_t MLIB_DivSat_F16ll(frac32_t f32num, frac32_t f32denom) frac32_t MLIB_DivSat_F32ls(frac32_t f32num, frac16_t f16denom) frac32_t MLIB_DivSat_F32(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_DivSat_A32as(acc32_t a32num, frac16_t f16denom) Function use The use of the MLIB_DivSat function is shown in the following example: static frac32_t f32num, f32denom, f32result; f32num = FRAC32(0.4); /* f32num = 0.4 */ f32denom = FRAC32(-0.02); /* f32denom = */ /* f32result = f32num / f32denom */ f32result = MLIB_DivSat_F32(f32Num, f32denom); 2.11 MLIB_Div1Q The MLIB_Div1Q functions return the single-quadrant fractional division of the numerator and denominator. The numerator and denominator must be non-negative numbers, otherwise the function returns undefined results. The function does not saturate the output. See the following equation: Equation 9. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <0 ; 1). The function is only defined for: nominator < denominator, and both are non-negative. The function returns undefined results out of this condition. Accumulator output - the output is the accumulator type, where the result is greater than or equal to Freescale Semiconductor, Inc.

39 The available versions of the MLIB_Div1Q function are shown in the following table: Function name Input type Result type Num. Denom. Table Function versions Description Chapter 2 Algorithms in detail MLIB_Div1Q_F16 frac16_t frac16_t frac16_t Division of a non-negative 16-bit fractional numerator and denominator. The output is within the range <0 ; 1). MLIB_Div1Q_F16ls frac32_t frac16_t frac16_t Division of a non-negative 32-bit fractional numerator by a nonnegative 16-bit fractional denominator; the output is a nonnegative 16-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1Q_F16ll frac32_t frac32_t frac16_t Division of a non-negative 32-bit fractional numerator and denominator; the output is a non-negative 16-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1Q_F32ls frac32_t frac16_t frac32_t Division of a non-negative 32-bit fractional numerator by a nonnegative 16-bit fractional denominator; the output is a nonnegative 32-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1Q_F32 frac32_t frac32_t frac32_t Division of a non-negative 32-bit fractional numerator and denominator. The output is within the range <0 ; 1). MLIB_Div1Q_A32ss frac16_t frac16_t acc32_t Division of a non-negative 16-bit fractional numerator and denominator; the output is a non-negative 32-bit accumulator result. The output is greater than or equal to 0. MLIB_Div1Q_A32ls frac32_t frac16_t acc32_t Division of a non-negative 32-bit fractional numerator by a nonnegative 16-bit fractional denominator; the output is a nonnegative 32-bit accumulator result. The output is greater than or equal to 0. MLIB_Div1Q_A32ll frac32_t frac32_t acc32_t Division of a non-negative 32-bit fractional numerator and denominator; the output is a non-negative 32-bit accumulator result. The output is greater than or equal to 0. MLIB_Div1Q_A32as acc32_t frac16_t acc32_t Division of a non-negative 32-bit accumulator numerator by a non-negative 16-bit fractional denominator; the output is a 32-bit accumulator result. The output is greater than or equal to Declaration The available MLIB_Div1Q functions have the following declarations: frac16_t MLIB_Div1Q_F16(frac16_t f16num, frac16_t f16denom) frac16_t MLIB_Div1Q_F16ls(frac32_t f32num, frac16_t f16denom) frac16_t MLIB_Div1Q_F16ll(frac32_t f32num, frac32_t f32denom) frac32_t MLIB_Div1Q_F32ls(frac32_t f32num, frac16_t f16denom) frac32_t MLIB_Div1Q_F32(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_Div1Q_A32ss(frac16_t f16num, frac16_t f16denom) acc32_t MLIB_Div1Q_A32ls(frac32_t f32num, frac16_t f16denom) acc32_t MLIB_Div1Q_A32ll(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_Div1Q_A32as(acc32_t a32num, frac16_t f16denom) Freescale Semiconductor, Inc. 39

40 MLIB_Div1QSat Function use The use of the MLIB_Div1Q function is shown in the following example: static frac32_t f32num, f32denom, f32result; f32num = FRAC32(0.2); /* f32num = 0.2 */ f32denom = FRAC32(0.865); /* f32denom = */ /* f32result = f32num / f32denom */ f32result = MLIB_Div1Q_F32(f32Num, f32denom); 2.12 MLIB_Div1QSat The MLIB_Div1QSat functions return the fractional division of the numerator and denominator. The numerator and denominator must be non-negative numbers. The function saturates the output. See the following equation: Equation 10. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <0 ; 1). The result may saturate. Accumulator output - the output is the accumulator type, where the result is greater than or equal to 0. The available versions of the MLIB_Div1QSat function are shown in the following table: Function name Input type Result type Num. Denom. Table Function versions Description MLIB_Div1QSat_F16 frac16_t frac16_t frac16_t Division of a non-negative 16-bit fractional numerator and denominator. The output is within the range <0 ; 1). Table continues on the next page Freescale Semiconductor, Inc.

41 Table Function versions (continued) Function name Input type Result type Num. Denom. Chapter 2 Algorithms in detail Description MLIB_Div1QSat_F16ls frac32_t frac16_t frac16_t Division of a non-negative 32-bit fractional numerator by a non-negative 16-bit fractional denominator; the output is a non-negative 16-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1QSat_F16ll frac32_t frac32_t frac16_t Division of a non-negative 32-bit fractional numerator and denominator; the output is a non-negative 16-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1QSat_F32ls frac32_t frac16_t frac32_t Division of a non-negative 32-bit fractional numerator by a non-negative 16-bit fractional denominator; the output is a non-negative 32-bit fractional result. The output is within the range <0 ; 1). MLIB_Div1QSat_F32 frac32_t frac32_t frac32_t Division of a non-negative 32-bit fractional numerator and denominator. The output is within the range <0 ; 1). MLIB_Div1QSat_A32as acc32_t frac16_t acc32_t Division of a non-negative 32-bit accumulator numerator by a non-negative 16-bit fractional denominator; the output is a 32-bit accumulator result. The output is greater than or equal to Declaration The available MLIB_Div1QSat functions have the following declarations: frac16_t MLIB_Div1QSat_F16(frac16_t f16num, frac16_t f16denom) frac16_t MLIB_Div1QSat_F16ls(frac32_t f32num, frac16_t f16denom) frac16_t MLIB_Div1QSat_F16ll(frac32_t f32num, frac32_t f32denom) frac32_t MLIB_Div1QSat_F32ls(frac32_t f32num, frac16_t f16denom) frac32_t MLIB_Div1QSat_F32(frac32_t f32num, frac32_t f32denom) acc32_t MLIB_Div1QSat_A32as(acc32_t a32num, frac16_t f16denom) Function use The use of the MLIB_Div1QSat function is shown in the following example: static frac32_t f32num, f32result; static frac16_t f16denom; f32num = FRAC32(0.02); /* f32num = 0.02 */ f16denom = FRAC16(0.4); /* f16denom = 0.4 */ /* f32result = f32num / f16denom */ f32result = MLIB_Div1QSat_F32ls(f32Num, f16denom); Freescale Semiconductor, Inc. 41

42 MLIB_Log MLIB_Log2 The MLIB_Log2 functions return the binary logarithm of the input. See the following equation: Equation 11. Algorithm formula Available versions This function is available in the following versions: Unsigned integer output - the output is the unsigned integer result. The available versions of the MLIB_Log2 function are shown in the following table. Table Function versions Function name Input type Result type Description MLIB_Log2_U16 uint16_t uint16_t Binary logarithm of a 16-bit unsigned integer value. The output is greater than or equal to Declaration The available MLIB_Log2 functions have the following declarations: uint16_t MLIB_Log2_U16(uint16_t u16val) Function use The use of the MLIB_Log2 function is shown in the following example: static uint16_t u16result, u16val; u16val = 5; /* u16val = 5 */ 42 Freescale Semiconductor, Inc.

43 Chapter 2 Algorithms in detail /* u16result = log2(u16val) */ u16result = MLIB_Log2_U16(u16Val); 2.14 MLIB_Mac The MLIB_Mac functions return the sum of the input accumulator, and the fractional product of two multiplicands. The function does not saturate the output. See the following equation: Equation 12. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may overflow. Accumulator output with mixed inputs - the output is the accumulator type, where the result can be out of the range <-1 ; 1). The accumulator is the accumulator type, the multiplicands are the fractional types. The result may overflow. The available versions of the MLIB_Mac function are shown in the following table. Table Function versions Function name Input type Result type Accum. Mult. 1 Mult. 2 Description MLIB_Mac_F16 frac16_t frac16_t frac16_t frac16_t The upper 16-bit portion [16..31] of the fractional product (of two 16-bit fractional multiplicands) is added to a 16-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_Mac_F32lss frac32_t frac16_t frac16_t frac32_t The 32-bit fractional product (of two 16-bit fractional multiplicands) is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_Mac_F32 frac32_t frac32_t frac32_t frac32_t The upper 32-bit portion [32..63] of the fractional product (of two 32-bit fractional multiplicands) is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_Mac_A32ass acc32_t frac16_t frac16_t acc32_t The upper 16-bit portion [16..31] of the fractional product (of two 16-bit fractional multiplicands) is added to a 32-bit accumulator. The output may be out of the range <-1 ; 1). Freescale Semiconductor, Inc. 43

44 MLIB_MacSat Declaration The available MLIB_Mac functions have the following declarations: frac16_t MLIB_Mac_F16(frac16_t f16accum, frac16_t f16mult1, frac16_t f16mult2) frac32_t MLIB_Mac_F32lss(frac32_t f32accum, frac16_t f16mult1, frac16_t f16mult2) frac32_t MLIB_Mac_F32(frac32_t f32accum, frac32_t f32mult1, frac32_t f32mult2) acc32_t MLIB_Mac_A32ass(acc32_t a32accum, frac16_t f16mult1, frac16_t f16mult2) Function use The use of the MLIB_Mac function is shown in the following example: static frac32_t f32accum, f32result; static frac16_t f16mult1, f16mult2; f32accum = FRAC32(0.3); /* f32accum = 0.3 */ f16mult1 = FRAC16(0.1); /* f16mult1 = 0.1 */ f16mult2 = FRAC16(-0.2); /* f16mult2 = -0.2 */ /* f32result = f32accum + f16mult1 * f16mult2 */ f32result = MLIB_Mac_F32lss(f32Accum, f16mult1, f16mult2); 2.15 MLIB_MacSat The MLIB_MacSat functions return the sum of the input accumulator and the fractional product of two multiplicands. The function saturates the output. See the following equation: Equation 13. Algorithm formula Available versions This function is available in the following versions: 44 Freescale Semiconductor, Inc.

45 Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may saturate. The available versions of the MLIB_MacSat function are shown in the following table. Table Function versions Function name Input type Result type Accum. Mult. 1 Mult. 2 Chapter 2 Algorithms in detail Description MLIB_MacSat_F16 frac16_t frac16_t frac16_t frac16_t The upper 16-bit portion [16..31] of the fractional product (of two 16-bit fractional multiplicands) is added to a 16-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_MacSat_F32lss frac32_t frac16_t frac16_t frac32_t The 32-bit fractional product (of two 16-bit fractional multiplicands) is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_MacSat_F32 frac32_t frac32_t frac32_t frac32_t The upper 32-bit portion [32..63] of the fractional product (of two 32-bit fractional multiplicands) is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1) Declaration The available MLIB_MacSat functions have the following declarations: frac16_t MLIB_MacSat_F16(frac16_t f16accum, frac16_t f16mult1, frac16_t f16mult2) frac32_t MLIB_MacSat_F32lss(frac32_t f32accum, frac16_t f16mult1, frac16_t f16mult2) frac32_t MLIB_MacSat_F32(frac32_t f32accum, frac32_t f32mult1, frac32_t f32mult2) Function use The use of the MLIB_MacSat function is shown in the following example: static frac16_t f16mult1, f16mult2; static frac32_t f32accum, f32result; f32accum = FRAC32(-0.7); /* f32accum = -0.7 */ f16mult1 = FRAC16(-1.0); /* f16mult1 = -1.0 */ f16mult2 = FRAC16(0.8); /* f16mult2 = 0.8 */ /* f32result = sat(f32accum + f16mult1 * f16mult2) */ f32result = MLIB_MacSat_F32lss(f32Accum, f16mult1, f16mult2); Freescale Semiconductor, Inc. 45

46 MLIB_MacRnd 2.16 MLIB_MacRnd The MLIB_MacRnd functions return the sum of the input accumulator and the rounded fractional product of two multiplicands. The round method is the round to nearest. The function does not saturate the output. See the following equation: Equation 14. Algorithm formula Available versions This function is available in the following versions: Fractional output - the output is the fractional portion of the result; the result is within the range <-1 ; 1). The result may overflow. Accumulator output with mixed inputs - the output is the accumulator type where the result can be out of the range <-1 ; 1). The accumulator is the accumulator type, the multiplicands are the fractional types. The result may overflow. The available versions of the MLIB_MacRnd function are shown in the following table. Table Function versions Function name Input type Result type Accum. Mult. 1 Mult. 2 Description MLIB_MacRnd_F16 frac16_t frac16_t frac16_t frac16_t The fractional product (of two 16-bit fractional multiplicands), rounded to the upper 16 bits, is added to a 16-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_MacRnd_F32lls frac32_t frac32_t frac16_t frac32_t The fractional product (of a 32-bit and 16-bit fractional multiplicand), rounded to the upper 32 bits [16..48], is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_MacRnd_F32 frac32_t frac32_t frac32_t frac32_t The fractional product (of two 32-bit fractional multiplicands), rounded to the upper 32 bits [32..63], is added to a 32-bit fractional accumulator. The output is within the range <-1 ; 1). MLIB_MacRnd_A32ass acc32_t frac16_t frac16_t acc32_t The fractional product (of two 16-bit fractional multiplicands), rounded to the upper 16 bits [16..31], is added to a 32-bit accumulator. The output may be out of the range <-1 ; 1). 46 Freescale Semiconductor, Inc.

47 Chapter 2 Algorithms in detail Declaration The available MLIB_MacRnd functions have the following declarations: frac16_t MLIB_MacRnd_F16(frac16_t f16accum, frac16_t f16mult1, frac16_t f16mult2) frac32_t MLIB_MacRnd_F32lls(frac32_t f32accum, frac32_t f32mult1, frac16_t f16mult2) frac32_t MLIB_MacRnd_F32(frac32_t f32accum, frac32_t f32mult1, frac32_t f32mult2) acc32_t MLIB_MacRnd_A32ass(acc32_t a32accum, frac16_t f16mult1, frac16_t f16mult2) Function use The use of the MLIB_MacRnd function is shown in the following example: static frac16_t f16accum, f16mult1, f16mult2, f16result; f16accum = FRAC16(0.3); /* f16accum = 0.3 */ f16mult1 = FRAC16(0.1); /* f16mult1 = 0.1 */ f16mult2 = FRAC16(-0.2); /* f16mult2 = -0.2 */ /* f16result = round(f16accum + f16mult1 * f16mult2) */ f16result = MLIB_MacRnd_F16(f16Accum, f16mult1, f16mult2); 2.17 MLIB_MacRndSat The MLIB_MacRndSat functions return the sum of the input accumulator and the rounded fractional product of two multiplicands. The round method is the round to nearest. The function saturates the output. See the following equation: Equation 15. Algorithm formula Available versions This function is available in the following versions: Freescale Semiconductor, Inc. 47

MLIB User's Guide. ARM Cortex M4

MLIB User's Guide. ARM Cortex M4 MLIB User's Guide ARM Cortex M4 Document Number: CM4MLIBUG Rev. 3, 08/2016 2 NXP Semiconductors Contents Section number Title Page Chapter 1 Library 1.1 Introduction... 7 1.2 Library integration into project