MLIB User's Guide

MLIB User's Guide
ARM® Cortex® M7F
Document Number: CM7FMLIBUG
Rev. 0, 10/2015
MLIB User's Guide, Rev. 0, 10/2015
2
Freescale Semiconductor, Inc.
Contents
Section number
Title
Page
Chapter 1
Library
1.1
1.2
1.3
Introduction.................................................................................................................................................................... 13
1.1.1
Overview............................................................................................................................................................13
1.1.2
Data types.......................................................................................................................................................... 13
1.1.3
API definition.................................................................................................................................................... 14
1.1.4
Supported compilers.......................................................................................................................................... 15
1.1.5
Special issues..................................................................................................................................................... 15
Library integration into project (Keil µVision) ............................................................................................................. 15
1.2.1
Freescale pack installation.................................................................................................................................15
1.2.2
New project........................................................................................................................................................16
1.2.3
Linking the files into the project........................................................................................................................18
1.2.4
Library path setup.............................................................................................................................................. 20
Library integration into project (IAR Embedded Workbench) ..................................................................................... 22
1.3.1
New project........................................................................................................................................................22
1.3.2
Library path variable..........................................................................................................................................24
1.3.3
Linking the files into the project........................................................................................................................25
1.3.4
Library path setup.............................................................................................................................................. 26
Chapter 2
Algorithms in detail
2.1
2.2
MLIB_Abs......................................................................................................................................................................29
2.1.1
Available versions............................................................................................................................................. 29
2.1.2
Declaration.........................................................................................................................................................29
2.1.3
Function use.......................................................................................................................................................30
MLIB_AbsSat.................................................................................................................................................................30
2.2.1
Available versions............................................................................................................................................. 30
2.2.2
Declaration.........................................................................................................................................................31
2.2.3
Function use.......................................................................................................................................................31
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
3
Section number
2.3
2.4
2.5
2.6
2.7
2.8
2.9
Title
Page
MLIB_Add..................................................................................................................................................................... 31
2.3.1
Available versions............................................................................................................................................. 31
2.3.2
Declaration.........................................................................................................................................................32
2.3.3
Function use.......................................................................................................................................................32
MLIB_AddSat................................................................................................................................................................ 33
2.4.1
Available versions............................................................................................................................................. 33
2.4.2
Declaration.........................................................................................................................................................33
2.4.3
Function use.......................................................................................................................................................34
MLIB_Add4................................................................................................................................................................... 34
2.5.1
Available versions............................................................................................................................................. 34
2.5.2
Declaration.........................................................................................................................................................35
2.5.3
Function use.......................................................................................................................................................35
MLIB_Add4Sat.............................................................................................................................................................. 35
2.6.1
Available versions............................................................................................................................................. 36
2.6.2
Declaration.........................................................................................................................................................36
2.6.3
Function use.......................................................................................................................................................36
MLIB_Clb...................................................................................................................................................................... 37
2.7.1
Available versions............................................................................................................................................. 37
2.7.2
Declaration.........................................................................................................................................................37
2.7.3
Function use.......................................................................................................................................................37
MLIB_Conv................................................................................................................................................................... 38
2.8.1
Available versions............................................................................................................................................. 38
2.8.2
Declaration.........................................................................................................................................................39
2.8.3
Function use.......................................................................................................................................................39
MLIB_ConvSc............................................................................................................................................................... 39
2.9.1
Available versions............................................................................................................................................. 40
2.9.2
Declaration.........................................................................................................................................................40
2.9.3
Function use.......................................................................................................................................................41
MLIB User's Guide, Rev. 0, 10/2015
4
Freescale Semiconductor, Inc.
Section number
Title
Page
2.10 MLIB_Div...................................................................................................................................................................... 41
2.10.1 Available versions............................................................................................................................................. 41
2.10.2 Declaration.........................................................................................................................................................42
2.10.3 Function use.......................................................................................................................................................43
2.11 MLIB_DivSat................................................................................................................................................................. 43
2.11.1 Available versions............................................................................................................................................. 43
2.11.2 Declaration.........................................................................................................................................................44
2.11.3 Function use.......................................................................................................................................................44
2.12 MLIB_Div1Q................................................................................................................................................................. 45
2.12.1 Available versions............................................................................................................................................. 45
2.12.2 Declaration.........................................................................................................................................................46
2.12.3 Function use.......................................................................................................................................................46
2.13 MLIB_Div1QSat............................................................................................................................................................ 47
2.13.1 Available versions............................................................................................................................................. 47
2.13.2 Declaration.........................................................................................................................................................48
2.13.3 Function use.......................................................................................................................................................48
2.14 MLIB_Log2....................................................................................................................................................................48
2.14.1 Available versions............................................................................................................................................. 48
2.14.2 Declaration.........................................................................................................................................................49
2.14.3 Function use.......................................................................................................................................................49
2.15 MLIB_Mac..................................................................................................................................................................... 49
2.15.1 Available versions............................................................................................................................................. 49
2.15.2 Declaration.........................................................................................................................................................50
2.15.3 Function use.......................................................................................................................................................50
2.16 MLIB_MacSat................................................................................................................................................................51
2.16.1 Available versions............................................................................................................................................. 51
2.16.2 Declaration.........................................................................................................................................................52
2.16.3 Function use.......................................................................................................................................................52
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
5
Section number
Title
Page
2.17 MLIB_MacRnd.............................................................................................................................................................. 53
2.17.1 Available versions............................................................................................................................................. 53
2.17.2 Declaration.........................................................................................................................................................54
2.17.3 Function use.......................................................................................................................................................54
2.18 MLIB_MacRndSat......................................................................................................................................................... 54
2.18.1 Available versions............................................................................................................................................. 54
2.18.2 Declaration.........................................................................................................................................................55
2.18.3 Function use.......................................................................................................................................................55
2.19 MLIB_Mac4................................................................................................................................................................... 56
2.19.1 Available versions............................................................................................................................................. 56
2.19.2 Declaration.........................................................................................................................................................56
2.19.3 Function use.......................................................................................................................................................57
2.20 MLIB_Mac4Sat..............................................................................................................................................................57
2.20.1 Available versions............................................................................................................................................. 57
2.20.2 Declaration.........................................................................................................................................................58
2.20.3 Function use.......................................................................................................................................................58
2.21 MLIB_Mac4Rnd............................................................................................................................................................ 58
2.21.1 Available versions............................................................................................................................................. 59
2.21.2 Declaration.........................................................................................................................................................59
2.21.3 Function use.......................................................................................................................................................59
2.22 MLIB_Mac4RndSat....................................................................................................................................................... 60
2.22.1 Available versions............................................................................................................................................. 60
2.22.2 Declaration.........................................................................................................................................................61
2.22.3 Function use.......................................................................................................................................................61
2.23 MLIB_Msu..................................................................................................................................................................... 61
2.23.1 Available versions............................................................................................................................................. 61
2.23.2 Declaration.........................................................................................................................................................62
2.23.3 Function use.......................................................................................................................................................62
MLIB User's Guide, Rev. 0, 10/2015
6
Freescale Semiconductor, Inc.
Section number
Title
Page
2.24 MLIB_MsuSat................................................................................................................................................................63
2.24.1 Available versions............................................................................................................................................. 63
2.24.2 Declaration.........................................................................................................................................................64
2.24.3 Function use.......................................................................................................................................................64
2.25 MLIB_MsuRnd.............................................................................................................................................................. 64
2.25.1 Available versions............................................................................................................................................. 65
2.25.2 Declaration.........................................................................................................................................................65
2.25.3 Function use.......................................................................................................................................................65
2.26 MLIB_MsuRndSat......................................................................................................................................................... 66
2.26.1 Available versions............................................................................................................................................. 66
2.26.2 Declaration.........................................................................................................................................................67
2.26.3 Function use.......................................................................................................................................................67
2.27 MLIB_Msu4................................................................................................................................................................... 68
2.27.1 Available versions............................................................................................................................................. 68
2.27.2 Declaration.........................................................................................................................................................68
2.27.3 Function use.......................................................................................................................................................69
2.28 MLIB_Msu4Sat..............................................................................................................................................................69
2.28.1 Available versions............................................................................................................................................. 69
2.28.2 Declaration.........................................................................................................................................................70
2.28.3 Function use.......................................................................................................................................................70
2.29 MLIB_Msu4Rnd............................................................................................................................................................ 70
2.29.1 Available versions............................................................................................................................................. 71
2.29.2 Declaration.........................................................................................................................................................71
2.29.3 Function use.......................................................................................................................................................71
2.30 MLIB_Msu4RndSat....................................................................................................................................................... 72
2.30.1 Available versions............................................................................................................................................. 72
2.30.2 Declaration.........................................................................................................................................................73
2.30.3 Function use.......................................................................................................................................................73
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
7
Section number
Title
Page
2.31 MLIB_Mul..................................................................................................................................................................... 73
2.31.1 Available versions............................................................................................................................................. 74
2.31.2 Declaration.........................................................................................................................................................74
2.31.3 Function use.......................................................................................................................................................75
2.32 MLIB_MulSat................................................................................................................................................................ 75
2.32.1 Available versions............................................................................................................................................. 75
2.32.2 Declaration.........................................................................................................................................................76
2.32.3 Function use.......................................................................................................................................................76
2.33 MLIB_MulNeg...............................................................................................................................................................77
2.33.1 Available versions............................................................................................................................................. 77
2.33.2 Declaration.........................................................................................................................................................78
2.33.3 Function use.......................................................................................................................................................78
2.34 MLIB_MulRnd...............................................................................................................................................................78
2.34.1 Available versions............................................................................................................................................. 79
2.34.2 Declaration.........................................................................................................................................................79
2.34.3 Function use.......................................................................................................................................................80
2.35 MLIB_MulRndSat..........................................................................................................................................................80
2.35.1 Available versions............................................................................................................................................. 80
2.35.2 Declaration.........................................................................................................................................................81
2.35.3 Function use.......................................................................................................................................................81
2.36 MLIB_MulNegRnd........................................................................................................................................................ 82
2.36.1 Available versions............................................................................................................................................. 82
2.36.2 Declaration.........................................................................................................................................................83
2.36.3 Function use.......................................................................................................................................................83
2.37 MLIB_Neg..................................................................................................................................................................... 84
2.37.1 Available versions............................................................................................................................................. 84
2.37.2 Declaration.........................................................................................................................................................84
2.37.3 Function use.......................................................................................................................................................84
MLIB User's Guide, Rev. 0, 10/2015
8
Freescale Semiconductor, Inc.
Section number
Title
Page
2.38 MLIB_NegSat................................................................................................................................................................ 85
2.38.1 Available versions............................................................................................................................................. 85
2.38.2 Declaration.........................................................................................................................................................85
2.38.3 Function use.......................................................................................................................................................86
2.39 MLIB_Rcp......................................................................................................................................................................86
2.39.1 Available versions............................................................................................................................................. 86
2.39.2 Declaration.........................................................................................................................................................87
2.39.3 Function use.......................................................................................................................................................87
2.40 MLIB_Rcp1Q.................................................................................................................................................................87
2.40.1 Available versions............................................................................................................................................. 88
2.40.2 Declaration.........................................................................................................................................................88
2.40.3 Function use.......................................................................................................................................................88
2.41 MLIB_Rnd..................................................................................................................................................................... 89
2.41.1 Available versions............................................................................................................................................. 89
2.41.2 Declaration.........................................................................................................................................................89
2.41.3 Function use.......................................................................................................................................................89
2.42 MLIB_RndSat................................................................................................................................................................ 90
2.42.1 Available versions............................................................................................................................................. 90
2.42.2 Declaration.........................................................................................................................................................90
2.42.3 Function use.......................................................................................................................................................90
2.43 MLIB_Sat....................................................................................................................................................................... 91
2.43.1 Available versions............................................................................................................................................. 91
2.43.2 Declaration.........................................................................................................................................................91
2.43.3 Function use.......................................................................................................................................................92
2.44 MLIB_Sh1L................................................................................................................................................................... 92
2.44.1 Available versions............................................................................................................................................. 92
2.44.2 Declaration.........................................................................................................................................................93
2.44.3 Function use.......................................................................................................................................................93
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
9
Section number
Title
Page
2.45 MLIB_Sh1LSat.............................................................................................................................................................. 93
2.45.1 Available versions............................................................................................................................................. 93
2.45.2 Declaration.........................................................................................................................................................94
2.45.3 Function use.......................................................................................................................................................94
2.46 MLIB_Sh1R................................................................................................................................................................... 94
2.46.1 Available versions............................................................................................................................................. 94
2.46.2 Declaration.........................................................................................................................................................95
2.46.3 Function use.......................................................................................................................................................95
2.47 MLIB_ShL..................................................................................................................................................................... 95
2.47.1 Available versions............................................................................................................................................. 96
2.47.2 Declaration.........................................................................................................................................................96
2.47.3 Function use.......................................................................................................................................................96
2.48 MLIB_ShLSat................................................................................................................................................................ 97
2.48.1 Available versions............................................................................................................................................. 97
2.48.2 Declaration.........................................................................................................................................................97
2.48.3 Function use.......................................................................................................................................................97
2.49 MLIB_ShR..................................................................................................................................................................... 98
2.49.1 Available versions............................................................................................................................................. 98
2.49.2 Declaration.........................................................................................................................................................99
2.49.3 Function use.......................................................................................................................................................99
2.50 MLIB_ShLBi..................................................................................................................................................................99
2.50.1 Available versions............................................................................................................................................. 99
2.50.2 Declaration.........................................................................................................................................................100
2.50.3 Function use.......................................................................................................................................................100
2.51 MLIB_ShLBiSat.............................................................................................................................................................100
2.51.1 Available versions............................................................................................................................................. 101
2.51.2 Declaration.........................................................................................................................................................101
2.51.3 Function use.......................................................................................................................................................101
MLIB User's Guide, Rev. 0, 10/2015
10
Freescale Semiconductor, Inc.
Section number
Title
Page
2.52 MLIB_ShRBi................................................................................................................................................................. 102
2.52.1 Available versions............................................................................................................................................. 102
2.52.2 Declaration.........................................................................................................................................................103
2.52.3 Function use.......................................................................................................................................................103
2.53 MLIB_ShRBiSat............................................................................................................................................................ 103
2.53.1 Available versions............................................................................................................................................. 104
2.53.2 Declaration.........................................................................................................................................................104
2.53.3 Function use.......................................................................................................................................................104
2.54 MLIB_Sign.....................................................................................................................................................................105
2.54.1 Available versions............................................................................................................................................. 105
2.54.2 Declaration.........................................................................................................................................................105
2.54.3 Function use.......................................................................................................................................................106
2.55 MLIB_Sub......................................................................................................................................................................106
2.55.1 Available versions............................................................................................................................................. 106
2.55.2 Declaration.........................................................................................................................................................107
2.55.3 Function use.......................................................................................................................................................107
2.56 MLIB_SubSat.................................................................................................................................................................108
2.56.1 Available versions............................................................................................................................................. 108
2.56.2 Declaration.........................................................................................................................................................108
2.56.3 Function use.......................................................................................................................................................108
2.57 MLIB_Sub4....................................................................................................................................................................109
2.57.1 Available versions............................................................................................................................................. 109
2.57.2 Declaration.........................................................................................................................................................110
2.57.3 Function use.......................................................................................................................................................110
2.58 MLIB_Sub4Sat...............................................................................................................................................................110
2.58.1 Available versions............................................................................................................................................. 110
2.58.2 Declaration.........................................................................................................................................................111
2.58.3 Function use.......................................................................................................................................................111
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
11
MLIB User's Guide, Rev. 0, 10/2015
12
Freescale Semiconductor, Inc.
Chapter 1
Library
1.1 Introduction
1.1.1 Overview
This user's guide describes the Math Library (MLIB) for the family of ARM Cortex M7F
core-based microcontrollers. This library contains optimized functions.
1.1.2 Data types
MLIB supports several data types: (un)signed integer, fractional, and accumulator, and
floating point. 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 floating-point data types are capable of storing real numbers in
wide dynamic ranges. The type is represented by binary digits and an exponent. The
exponent allows scaling the numbers from extremely small to extremely big numbers.
Because the exponent takes part of the type, the overall resolution of the number is
reduced when compared to the fixed-point type of the same size.
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 —<-32768 ; 32767> with the minimum resolution of 1
Unsigned 32-bit integer —<0 ; 4294967295> with the minimum resolution of 1
Signed 32-bit integer —<-2147483648 ; 2147483647> with the minimum resolution
of 1
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
13
Introduction
The following list shows the fractional types defined in the libraries:
• Fixed-point 16-bit fractional —<-1 ; 1 - 2-15> with the minimum resolution of 2-15
• Fixed-point 32-bit fractional —<-1 ; 1 - 2-31> with the minimum resolution of 2-31
The following list shows the accumulator types defined in the libraries:
• Fixed-point 16-bit accumulator —<-256.0 ; 256.0 - 2-7> with the minimum
resolution of 2-7
• Fixed-point 32-bit accumulator —<-65536.0 ; 65536.0 - 2-15> with the minimum
resolution of 2-15
The following list shows the floating-point types defined in the libraries:
• Floating point 32-bit single precision —<-3.40282 · 1038 ; 3.40282 · 1038> with the
minimum resolution of 2-23
1.1.3 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
float_t
FLT
f
MLIB User's Guide, Rev. 0, 10/2015
14
Freescale Semiconductor, Inc.
Chapter 1 Library
1.1.4 Supported compilers
MLIB for the ARM Cortex M7F core is written in . The library is built and tested using
the following compilers:
• IAR Embedded Workbench
• Keil µVision
For the IAR Embedded Workbench, the library is delivered in the mlib.a file.
For the Keil µVision, 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.
1.1.5 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 that round the result (the API contains Rnd) round to nearest
(half up).
1.2 Library integration into project (Keil µVision)
This section provides a step-by-step guide on how to quickly and easily include MLIB
into an empty project using Keil µVision. This example uses the Freescale
MKV58F1M0xxx22 part, and the default installation path (C:\Freescale\FSLESL
\CM7F_FSLESL_4.2_KEIL) is supposed. If you have a different installation path, use
that path instead.
1.2.1 Freescale pack installation
If the compiler has never been used to create any Freescale MCU-based projects before,
check whether the Freescale MCU pack for the particular device is installed. Follow these
steps:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
15
Library integration into project (Keil µVision)
1. Launch Keil µVision.
2. In the main menu, go to Project > Manage > Pack Installer….
3. In the left-hand dialog (under the Devices tab), expand the All Devices > Freescale
node.
4. Look for a line called "KVxx Series" and click it.
5. In the right-hand dialog (under the Packs tab), expand the Device Specific node.
6. Look for a node called "Keil::Kinetis_KVxx_DFP." If there are the Install or Update
options, click the button to install/update the package. See Figure 1-1.
7. When installed, the button has the "Up to date" title. Now close the Pack Installer.
Figure 1-1. Pack Installer
1.2.2 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Follow these steps to create a new project:
1. Launch Keil µVision.
2. In the main menu, select Project > New µVision Project…, and the Create New
Project dialog appears.
3. Navigate to the folder where you want to create the project, for example C:
\KeilProjects\MyProject01. Type the name of the project, for example MyProject01.
Click Save. See Figure 1-2.
MLIB User's Guide, Rev. 0, 10/2015
16
Freescale Semiconductor, Inc.
Chapter 1 Library
4.
5.
6.
7.
Figure 1-2. Create New Project dialog
In the next dialog, select the Software Packs in the very first box.
Type '' into the Search box, so that the device list is reduced to the devices.
Expand the node.
Click the MKV58F1M0xxx22 node, and then click OK. See Figure 1-3.
Figure 1-3. Select Device dialog
8. In the next dialog, expand the Device node, and tick the box next to the Startup node.
See Figure 1-4.
9. Expand the CMSIS node, and tick the box next to the CORE node.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
17
Library integration into project (Keil µVision)
Figure 1-4. Manage Run-Time Environment dialog
10. Click OK, and a new project is created. The new project is now visible in the lefthand part of Keil µVision. See Figure 1-5.
Figure 1-5. Project
11. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
12. Select the Target tab.
13. Select Use Single Precision in the Floating Point Hardware option. See Figure 1-5.
Figure 1-6. FPU
MLIB User's Guide, Rev. 0, 10/2015
18
Freescale Semiconductor, Inc.
Chapter 1 Library
1.2.3 Linking the files into the project
To include the library files in the project, create groups and add them.
1. Right-click the Target 1 node in the left-hand part of the Project tree, and select Add
Group… from the menu. A new group with the name New Group is added.
2. Click the newly created group, and press F2 to rename it to FSLESL.
3. Right-click the FSLESL node, and select Add Existing Files to Group 'FSLESL'…
from the menu.
4. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7F_FSLESL_4.2_KEIL\MLIB\Include, and select the mlib_fp.h file. If the file
does not appear, set the Files of type filter to Text file. Click Add. See Figure 1-7.
Figure 1-7. Adding .h files dialog
5. Navigate to the parent folder C:\Freescale\FSLESL\CM7F_FSLESL_4.2_KEIL
\MLIB, and select the mlib.lib file. If the file does not appear, set the Files of type
filter to Library file. Click Add. See Figure 1-8.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
19
Library integration into project (Keil µVision)
Figure 1-8. Adding .lib files dialog
6. Now, all necessary files are in the project tree; see Figure 1-9. Click Close.
Figure 1-9. Project workspace
1.2.4 Library path setup
The following steps show the inclusion of all dependent modules.
1. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
2. Select the C/C++ tab. See Figure 1-10.
3. In the Include Paths text box, type the following path (if there are more paths, they
must be separated by ';') or add it by clicking the … button next to the text box:
• "C:\Freescale\FSLESL\CM7F_FSLESL_4.2_KEIL\MLIB\Include"
4. Click OK.
5. Click OK in the main dialog.
MLIB User's Guide, Rev. 0, 10/2015
20
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-10. Library path addition
Type the #include syntax into the code. Include the library into a source file. In the new
project, it is necessary to create a source file:
1. Right-click the Source Group 1 node, and Add New Item to Group 'Source Group
1'… from the menu.
2. Select the C File (.c) option, and type a name of the file into the Name box, for
example 'main.c'. See Figure 1-11.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
21
Library integration into project (IAR Embedded Workbench)
Figure 1-11. Adding new source file dialog
3. Click Add, and a new source file is created and opened up.
4. In the opened source file, include the following line into the #include section, and
create a main function:
#include "mlib_fp.h"
int main(void)
{
while(1);
}
When you click the Build (F7) icon, the project will be compiled without errors.
1.3 Library integration into project (IAR Embedded
Workbench)
This section provides a step-by-step guide on how to quickly and easily include the
MLIB into an empty project using IAR Embedded Workbench. This example uses the
Freescale MKV58F1M0xxx22 part, and the default installation path (C:\Freescale
\FSLESL\CM7F_FSLESL_4.2_IAR) is supposed. If you have a different installation
path, then use that path instead.
MLIB User's Guide, Rev. 0, 10/2015
22
Freescale Semiconductor, Inc.
Chapter 1 Library
1.3.1 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Perform these steps to create a new project:
1. Launch IAR Embedded Workbench.
2. In the main menu, select Project > Create New Project… so that the "Create New
Project" dialog appears. See Figure 1-12.
Figure 1-12. Create New Project dialog
3. Expand the C node in the tree, and select the "main" node. Click OK.
4. Navigate to the folder where you want to create the project, for example, C:
\IARProjects\MyProject01. Type the name of the project, for example, MyProject01.
Click Save, and a new project is created. The new project is now visible in the lefthand part of IAR Embedded Workbench. See Figure 1-13.
Figure 1-13. New project
5. In the main menu, go to Project > Options…, and a dialog appears.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
23
Library integration into project (IAR Embedded Workbench)
6. In the Target tab, select the Device option, and click the button next to the dialog to
select the MCU. In this example, select Freescale > KV5x > Freescale
MKV58F1M0xxx22. Select VFPv5 single precision in the FPU option. Click OK.
See Figure 1-14.
Figure 1-14. Options dialog
1.3.2 Library path variable
To make the library integration easier, create a variable that will hold the information
about the library path.
1. In the main menu, go to Tools > Configure Custom Argument Variables…, and a
dialog appears.
2. Click the New Group button, and another dialog appears. In this dialog, type the
name of the group PATH, and click OK. See Figure 1-15.
MLIB User's Guide, Rev. 0, 10/2015
24
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-15. New Group
3. Click on the newly created group, and click the Add Variable button. A dialog
appears.
4. Type this name: FSLESL_LOC
5. To set up the value, look for the library by clicking the '…' button, or just type the
installation path into the box: C:\Freescale\FSLESL\CM7F_FSLESL_4.2_IAR. Click
OK.
6. In the main dialog, click OK. See Figure 1-16.
Figure 1-16. New variable
1.3.3 Linking the files into the project
To include the library files into the project, create groups and add them.
1. Go to the main menu Project > Add Group…
2. Type FSLESL, and click OK.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
25
Library integration into project (IAR Embedded Workbench)
3. Click on the newly created node FSLESL, go to Project > Add Group…, and create a
MLIB subgroup.
4. Click on the newly created node MLIB, and go to the main menu Project > Add
Files… See Figure 1-18.
5. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7F_FSLESL_4.2_IAR\MLIB\Include, and select the mlib_fp.h file. (If the file
does not appear, set the file-type filter to Source Files.) Click Open. See Figure 1-17.
6. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7F_FSLESL_4.2_IAR\MLIB, and select the mlib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
Figure 1-17. Add Files dialog
7. Now you will see the files added in the workspace. See Figure 1-18.
Figure 1-18. Project workspace
1.3.4 Library path setup
1. In the main menu, go to Project > Options…, and a dialog appears.
2. In the left-hand column, select C/C++ Compiler.
3. In the right-hand part of the dialog, click on the Preprocessor tab (it can be hidden in
the right; use the arrow icons for navigation).
4. In the text box (at the Additional include directories title), type the following folder
(using the created variable):
• $FSLESL_LOC$\MLIB\Include
5. Click OK in the main dialog. See Figure 1-19.
MLIB User's Guide, Rev. 0, 10/2015
26
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-19. Library path adition
Type the #include syntax into the code. Include the library included into the main.c file.
In the workspace tree, double-click the main.c file. After the main.c file opens up, include
the following line into the #include section:
#include "mlib_fp.h"
When you click the Make icon, the project will be compiled without errors.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
27
Library integration into project (IAR Embedded Workbench)
MLIB User's Guide, Rev. 0, 10/2015
28
Freescale Semiconductor, Inc.
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
2.1.1 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.
• Floating-point output - the output is a floating-point number; the result is a nonnegative value.
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).
MLIB_Abs_FLT
float_t
float_t
Absolute value of a 32-bit single precision floating-point value. The
output is a non-negative value.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
29
MLIB_AbsSat
2.1.2 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)
float_t MLIB_Abs_FLT(float_t fltVal)
2.1.3 Function use
The use of the MLIB_Abs function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac32_t f32Val;
void main(void)
{
f32Val = FRAC32(-0.354);
}
/* f32Val = -0.354 */
/* 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
2.2.1 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.
MLIB User's Guide, Rev. 0, 10/2015
30
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
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).
2.2.2 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)
2.2.3 Function use
The use of the MLIB_AbsSat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Val, f16Result;
void main(void)
{
f16Val = FRAC16(-0.835);
}
/* f16Val = -0.835 */
/*
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
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
31
MLIB_Add
2.3.1 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 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Add function are shown in the following table.
Table 2-3. Function versions
Function name
Input type
Addend 1
Addend 2
Result
type
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 32bit 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).
MLIB_Add_FLT
float_t
float_t
float_t
Addition of two 32-bit single precision floating-point
addends. The output is within the full range.
2.3.2 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)
float_t MLIB_Add_FLT(float_t fltAdd1, float_t fltAdd2)
2.3.3 Function use
The use of the MLIB_Add function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
32
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "mlib.h"
static acc32_t a32Result;
static frac16_t f16Add1, f16Add2;
void main(void)
{
f16Add1 = FRAC16(-0.8);
f16Add2 = FRAC16(-0.5);
}
/* f16Add1 = -0.8 */
/* f16Add2 = -0.5 */
/* a32Result = f16Add1 + f16Add2 */
a32Result = MLIB_Add_A32ss(f16Add1, f16Add2);
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
2.4.1 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.
Table 2-4. Function versions
Function name
Input type
Addend 1
Addend 2
Result
type
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).
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
33
MLIB_Add4
2.4.2 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)
2.4.3 Function use
The use of the MLIB_AddSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Add1, f32Add2, f32Result;
void main(void)
{
f32Add1 = FRAC32(-0.8);
f32Add2 = FRAC32(-0.5);
}
/* f32Add1 = -0.8 */
/* 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
2.5.1 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
MLIB User's Guide, Rev. 0, 10/2015
34
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_Add4 function are shown in the following table.
Table 2-5. Function versions
Function name
Input type
Add. 1
Add. 2
Add. 3
Result
type
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).
MLIB_Add4_FLT
float_t
float_t
float_t
float_t
float_t
Addition of four 32-bit single precision
floating-point addends. The output is within
the full range.
2.5.2 Declaration
The available MLIB_Add4 functions have the following declarations:
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)
float_t MLIB_Add4_FLT(float_t fltAdd1, float_t fltAdd2, float_t fltAdd3, float_t fltAdd4)
2.5.3 Function use
The use of the MLIB_Add4 function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac32_t f32Add1, f32Add2, f32Add3, f32Add4;
void main(void)
{
f32Add1 = FRAC32(-0.3);
f32Add2 = FRAC32(0.5);
f32Add3 = FRAC32(-0.2);
f32Add4 = FRAC32(-0.4);
}
/*
/*
/*
/*
f32Add1
f32Add2
f32Add3
f32Add4
=
=
=
=
-0.3 */
0.5 */
-0.2 */
-0.4 */
/* f32Result = f32Add1 + f32Add2 + f32Add3 + f32Add4 */
f32Result = MLIB_Add4_F32(f32Add1, f32Add2, f32Add3, f32Add4);
2.6 MLIB_Add4Sat
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
35
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
2.6.1 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_Add4Sat function are shown in the following table.
Table 2-6. Function versions
Function name
Input type
Add. 1
Add. 2
Add. 3
Add. 4
Result
type
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).
2.6.2 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)
2.6.3 Function use
The use of the MLIB_Add4Sat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Add1, f16Add2, f16Add3, f16Add4;
MLIB User's Guide, Rev. 0, 10/2015
36
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
void main(void)
{
f16Add1 = FRAC16(-0.7);
f16Add2 = FRAC16(0.9);
f16Add3 = FRAC16(0.4);
f16Add4 = FRAC16(0.7);
}
/*
/*
/*
/*
f16Add1
f16Add2
f16Add3
f16Add4
=
=
=
=
-0.7 */
0.9 */
0.4 */
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.
2.7.1 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>.
2.7.2 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)
2.7.3 Function use
The use of the MLIB_Clb function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
37
MLIB_Conv
#include "mlib.h"
static uint16_t u16Result;
static frac32_t f32Val;
void main(void)
{
f32Val = FRAC32(0.00000452);
}
/* f32Val = 0.00000452 */
/* u16Result = clb(f32Val) */
u16Result = MLIB_Clb_U16l(f32Val);
2.8 MLIB_Conv
The MLIB_Conv functions return the input value, converted to the output type.
2.8.1 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).
• Accumulator output - the output is the accumulator type, where the result may be out
of the range <-1 ; 1).
• Floating-point output - the output is a floating-point number; 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_F16f
float_t
frac16_t
Conversion of a 32-bit single precision floating-point value to a 16-bit
fractional value. The output is within the range <-1 ; 1). If the result is
out of this range, it is saturated.
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).
MLIB_Conv_F32f
float_t
frac32_t
Conversion of a 32-bit single precision floating-point value to a 32-bit
fractional value. The output is within the range <-1 ; 1). If the result is
out of this range, it is saturated.
MLIB_Conv_A32f
float_t
acc32_t
Conversion of a 32-bit single precision floating-point value to a 32-bit
accumulator value. The output is within the range <-65536.0 ;
65536.0). If the result is out of this range, it is saturated.
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
38
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Table 2-8. Function versions (continued)
Function name
Input type
Result type
Description
MLIB_Conv_FLTs
frac16_t
float_t
Conversion of a 16-bit fractional value to a 32-bit single precision
floating-point value. The output is within the range <-1 ; 1).
MLIB_Conv_FLTl
frac32_t
float_t
Conversion of a 32-bit fractional value to a 32-bit single precision
floating-point value. The output is within the range <-1 ; 1).
MLIB_Conv_FLTa
acc32_t
float_t
Conversion of a 32-bit accumulator value to a 32-bit single precision
floating-point value. The output is within the range <-65536.0 ;
65536.0).
2.8.2 Declaration
The available MLIB_Conv functions have the following declarations:
frac16_t MLIB_Conv_F16l(frac32_t f32Val)
frac16_t MLIB_Conv_F16f(float_t fltVal)
frac32_t MLIB_Conv_F32s(frac16_t f16Val)
frac32_t MLIB_Conv_F32f(float_t fltVal)
acc32_t MLIB_Conv_A32f(float_t fltVal)
float_t MLIB_Conv_FLTs(frac16_t f16Val)
float_t MLIB_Conv_FLTl(frac32_t f32Val)
float_t MLIB_Conv_FLTa(acc32_t a32Val)
2.8.3 Function use
The use of the MLIB_Conv function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16Val;
void main(void)
{
f16Val = FRAC16(-0.354);
}
/* f16Val = -0.354 */
/* f32Result = (frac32_t)f16Val << 16 */
f32Result = MLIB_Conv_F32s(f16Val);
2.9 MLIB_ConvSc
The MLIB_ConvSc functions return the input value converted to the output type using a
scale coefficient.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
39
MLIB_ConvSc
2.9.1 Available versions
The function is available in the following versions:
• Fractional output - the output is the fractional portion of the result. The input value is
divided by the scale to be within the range <-1 ; 1). The result may be saturated.
• Accumulator output - the output is the accumulator type, where the result may be out
of the range <-1 ; 1).
• Floating-point output - the output is a floating-point number. The input value is
multiplied by the scale to transform the fractional value into the real floating-point
number. The result is within the full range.
The available versions of the MLIB_ConvSc function are shown in the following table.
Table 2-9. Function versions
Function name
Input type
Value
Scale
Result
type
Description
MLIB_ConvSc_F16ff
float_t
float_t
float_t
Conversion of a 32-bit single precision floating-point value to
a 16-bit fractional value using a 32-bit single precision
floating-point scale. The output is within the range <-1 ; 1);
the result may saturate.
MLIB_ConvSc_F32ff
float_t
float_t
float_t
Conversion of a 32-bit single precision floating-point value to
a 32-bit fractional value using a 32-bit single precision
floating-point scale. The output is within the range <-1 ; 1);
the result may saturate.
MLIB_ConvSc_A32ff
float_t
float_t
float_t
Conversion of a 32-bit single precision floating-point value to
a 32-bit accumulator value using a 32-bit single precision
floating-point scale. The output is within the range
<-65536.0 ; 65536.0); the result may saturate.
MLIB_ConvSc_FLTsf frac16_t
float_t
float_t
Conversion of a 16-bit fractional value to a 32-bit single
precision floating-point value using a 32-bit single precision
floating-point scale. The output is within the range <-1 ; 1).
MLIB_ConvSc_FLTlf
frac32_t
float_t
float_t
Conversion of a 32-bit fractional value to a 32-bit single
precision floating-point value using a 32-bit single precision
floating-point scale. The output is within the range <-1 ; 1).
MLIB_ConvSc_FLTaf acc32_t
float_t
float_t
Conversion of a 32-bit accumulator value to a 32-bit single
precision floating-point value using a 32-bit single precision
floating-point scale. The output is within the range
<-65536.0 ; 65536.0); the result may saturate.
2.9.2 Declaration
The available MLIB_ConvSc functions have the following declarations:
MLIB User's Guide, Rev. 0, 10/2015
40
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
frac16_t MLIB_ConvSc_F16ff(float_t fltVal, float_t fltSc)
frac32_t MLIB_ConvSc_F32ff(float_t fltVal, float_t fltSc)
acc32_t MLIB_ConvSc_A32ff(float_t fltVal, float_t fltSc)
float_t MLIB_ConvSc_FLTsf(frac16_t f16Val, float_t fltSc)
float_t MLIB_ConvSc_FLTlf(frac32_t f32Val, float_t fltSc)
float_t MLIB_ConvSc_FLTaf(acc32_t a32Val, float_t fltSc)
2.9.3 Function use
The use of the MLIB_ConvSc function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static float_t fltVal, fltScale;
void main(void)
{
fltVal = -0.736;
fltScale = 435;
}
/* fltVal = -0.736 */
/* Scale is 435 */
/* f32Result = (frac32_t)((fltVal / fltScale) * 2 ^ 32) */
f32Result = MLIB_ConvSc_F32ff(fltVal, fltScale);
2.10 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
2.10.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
41
MLIB_Div
• Accumulator output - the output is the accumulator type, where the result may be out
of the range <-1 ; 1).
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Div function are shown in the following table:
Table 2-10. Function versions
Function name
Input type
Num.
Denom.
Result
type
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).
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).
MLIB_Div_FLT
float_t
float_t
float_t
Division of a 32-bit single precision floating-point numerator and
denominator. The output is within the full range.
2.10.2 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)
MLIB User's Guide, Rev. 0, 10/2015
42
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
acc32_t MLIB_Div_A32ll(frac32_t f32Num, frac32_t f32Denom)
acc32_t MLIB_Div_A32as(acc32_t a32Num, frac16_t f16Denom)
float_t MLIB_Div_FLT(float_t fltNum, float_t fltDenom)
2.10.3 Function use
The use of the MLIB_Div function is shown in the following example:
#include "mlib.h"
static frac32_t f32Num, f32Result;
static frac16_t f16Denom;
void main(void)
{
f32Num = FRAC32(0.2);
f16Denom = FRAC16(-0.495);
}
/* f32Num = 0.2 */
/* f16Denom = -0.495 */
/* f32Result = f32Num / f16Denom */
f32Result = MLIB_Div_F32ls(f32Num, f16Denom);
2.11 MLIB_DivSat
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
2.11.1 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).
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
43
MLIB_DivSat
The available versions of the MLIB_DivSat function are shown in the following table:
Table 2-11. Function versions
Function name
Input type
Num.
Denom.
Result
type
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).
2.11.2 Declaration
The available MLIB_DivSat functions have the following declarations:
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)
2.11.3 Function use
The use of the MLIB_DivSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Num, f32Denom, f32Result;
void main(void)
{
f32Num = FRAC32(0.4);
f32Denom = FRAC32(-0.02);
/* f32Num = 0.4 */
/* f32Denom = -0.02 */
/* f32Result = f32Num / f32Denom */
MLIB User's Guide, Rev. 0, 10/2015
44
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
}
f32Result = MLIB_DivSat_F32(f32Num, f32Denom);
2.12 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
2.12.1 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 0.
The available versions of the MLIB_Div1Q function are shown in the following table:
Table 2-12. Function versions
Function name
Input type
Num.
Denom.
Result
type
Description
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).
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
45
MLIB_Div1Q
Table 2-12. Function versions (continued)
Function name
Input type
Num.
Denom.
Result
type
Description
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 0.
2.12.2 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)
2.12.3 Function use
The use of the MLIB_Div1Q function is shown in the following example:
#include "mlib.h"
static frac32_t f32Num, f32Denom, f32Result;
void main(void)
{
f32Num = FRAC32(0.2);
f32Denom = FRAC32(0.865);
}
/* f32Num = 0.2 */
/* f32Denom = 0.865 */
/* f32Result = f32Num / f32Denom */
f32Result = MLIB_Div1Q_F32(f32Num, f32Denom);
MLIB User's Guide, Rev. 0, 10/2015
46
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.13 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
2.13.1 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:
Table 2-13. Function versions
Function name
Input type
Num.
Denom.
Result
type
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).
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 0.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
47
MLIB_Log2
2.13.2 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)
2.13.3 Function use
The use of the MLIB_Div1QSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Num, f32Result;
static frac16_t f16Denom;
void main(void)
{
f32Num = FRAC32(0.02);
f16Denom = FRAC16(0.4);
}
/* f32Num = 0.02 */
/* f16Denom = 0.4 */
/* f32Result = f32Num / f16Denom */
f32Result = MLIB_Div1QSat_F32ls(f32Num, f16Denom);
2.14 MLIB_Log2
The MLIB_Log2 functions return the binary logarithm of the input. See the following
equation:
Equation 11. Algorithm formula
2.14.1 Available versions
This function is available in the following versions:
• Unsigned integer output - the output is the unsigned integer result.
MLIB User's Guide, Rev. 0, 10/2015
48
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_Log2 function are shown in the following table.
Table 2-14. Function versions
Function name
MLIB_Log2_U16
Input type
Result type
uint16_t
uint16_t
Description
Binary logarithm of a 16-bit unsigned integer value. The output is
greater than or equal to 0.
2.14.2 Declaration
The available MLIB_Log2 functions have the following declarations:
uint16_t MLIB_Log2_U16(uint16_t u16Val)
2.14.3 Function use
The use of the MLIB_Log2 function is shown in the following example:
#include "mlib.h"
static uint16_t u16Result, u16Val;
void main(void)
{
u16Val = 5;
}
/* u16Val = 5 */
/* u16Result = log2(u16Val) */
u16Result = MLIB_Log2_U16(u16Val);
2.15 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
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
49
MLIB_Mac
2.15.1 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Mac function are shown in the following table.
Table 2-15. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
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).
MLIB_Mac_FLT
float_t
float_t
float_t
float_t
The product (of two 32-bit single-point floating-point
multiplicands) is added to a single-point floatingpoint accumulator. The output is within the full range.
2.15.2 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)
float_t MLIB_Mac_F32(float_t fltAccum, float_t fltMult1, float_t fltMult2)
MLIB User's Guide, Rev. 0, 10/2015
50
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.15.3 Function use
The use of the MLIB_Mac function is shown in the following example:
#include "mlib.h"
static frac32_t f32Accum, f32Result;
static frac16_t f16Mult1, f16Mult2;
void main(void)
{
f32Accum = FRAC32(0.3);
f16Mult1 = FRAC16(0.1);
f16Mult2 = FRAC16(-0.2);
}
/* f32Accum = 0.3 */
/* f16Mult1 = 0.1 */
/* f16Mult2 = -0.2 */
/* f32Result = f32Accum + f16Mult1 * f16Mult2 */
f32Result = MLIB_Mac_F32lss(f32Accum, f16Mult1, f16Mult2);
2.16 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
2.16.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
51
MLIB_MacSat
The available versions of the MLIB_MacSat function are shown in the following table.
Table 2-16. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
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).
2.16.2 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)
2.16.3 Function use
The use of the MLIB_MacSat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Mult1, f16Mult2;
static frac32_t f32Accum, f32Result;
void main(void)
{
f32Accum = FRAC32(-0.7);
f16Mult1 = FRAC16(-1.0);
f16Mult2 = FRAC16(0.8);
}
/* f32Accum = -0.7 */
/* f16Mult1 = -1.0 */
/* f16Mult2 = 0.8 */
/* f32Result = sat(f32Accum + f16Mult1 * f16Mult2) */
f32Result = MLIB_MacSat_F32lss(f32Accum, f16Mult1, f16Mult2);
MLIB User's Guide, Rev. 0, 10/2015
52
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.17 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
2.17.1 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 2-17. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
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).
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
53
MLIB_MacRndSat
2.17.2 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)
2.17.3 Function use
The use of the MLIB_MacRnd function is shown in the following example:
#include "mlib.h"
static frac16_t f16Accum, f16Mult1, f16Mult2, f16Result;
void main(void)
{
f16Accum = FRAC16(0.3);
f16Mult1 = FRAC16(0.1);
f16Mult2 = FRAC16(-0.2);
}
/* f16Accum = 0.3 */
/* f16Mult1 = 0.1 */
/* f16Mult2 = -0.2 */
/* f16Result = round(f16Accum + f16Mult1 * f16Mult2) */
f16Result = MLIB_MacRnd_F16(f16Accum, f16Mult1, f16Mult2);
2.18 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
2.18.1 Available versions
This function is available in the following versions:
MLIB User's Guide, Rev. 0, 10/2015
54
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
• 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_MacRndSat function are shown in the following
table.
Table 2-18. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
Description
MLIB_MacRndSat_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_MacRndSat_F32lls
frac32_t
frac32_t
frac16_t
frac32_t
The fractional product (of a 32-bit and 16-bit
fractional multiplicands), 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_MacRndSat_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).
2.18.2 Declaration
The available MLIB_MacRndSat functions have the following declarations:
frac16_t MLIB_MacRndSat_F16(frac16_t f16Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MacRndSat_F32lls(frac32_t f32Accum, frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MacRndSat_F32(frac32_t f32Accum, frac32_t f32Mult1, frac32_t f32Mult2)
2.18.3 Function use
The use of the MLIB_MacRndSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Accum, f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Accum = FRAC32(-0.7);
f32Mult1 = FRAC32(-1.0);
f32Mult2 = FRAC32(0.8);
/* f32Accum = -0.7 */
/* f32Mult1 = -1.0 */
/* f32Mult2 = 0.8 */
/* f32Result = sat(round(f32Accum + f32Mult1 * f32Mult2)) */
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
55
MLIB_Mac4
}
f32Result = MLIB_MacRndSat_F32(f32Accum, f32Mult1, f32Mult2);
2.19 MLIB_Mac4
The MLIB_Mac4 functions return the sum of two products of two pairs of multiplicands.
The function does not saturate the output. See the following equation:
Equation 16. Algorithm formula
2.19.1 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Mac4 function are shown in the following table.
Table 2-19. Function versions
Function name
Input type
Product 1
Mult. 1
Mult. 2
Product 2
Mult. 1
Result
type
Description
Mult. 2
MLIB_Mac4_F32ssss
frac16_t
frac16_t
frac16_t
frac16_t
frac32_t
Addition of two 32-bit fractional
products (of two 16-bit fractional
multiplicands). The output is within the
range <-1 ; 1).
MLIB_Mac4_FLT
float_t
float_t
float_t
float_t
float_t
Addition of two 32-bit single-point
floating-point products (of two 32-bit
single-point floating-point
multiplicands). The output is within the
full range.
2.19.2 Declaration
The available MLIB_Mac4 functions have the following declarations:
MLIB User's Guide, Rev. 0, 10/2015
56
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
frac32_t MLIB_Mac4_F32ssss(frac16_t f16Add1Mult1, frac16_t f16Add1Mult2, frac16_t
f16Add2Mult1, frac16_t f16Add2Mult2)
float_t MLIB_Mac4_FLT(float_t fltAdd1Mult1, float_t fltAdd1Mult2, float_t fltAdd2Mult1,
float_t fltAdd2Mult2)
2.19.3 Function use
The use of the MLIB_Mac4 function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2;
void main(void)
{
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
}
=
=
=
=
FRAC16(0.2);
FRAC16(-0.7);
FRAC16(0.3);
FRAC16(-0.25);
/*
/*
/*
/*
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
=
=
=
=
0.2 */
-0.7 */
0.3 */
-0.25 */
/* f32Result = f16Add1Mult1 * f16Add1Mult2 + f16Add2Mult1 * f16Add2Mult2*/
f32Result = MLIB_Mac4_F32ssss(f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2);
2.20 MLIB_Mac4Sat
The MLIB_Mac4Sat functions return the sum of two products of two pairs of
multiplicands. The function saturates the output. See the following equation:
Equation 17. Algorithm formula
2.20.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
57
MLIB_Mac4Rnd
The available versions of the MLIB_Mac4Sat function are shown in the following table.
Table 2-20. Function versions
Function name
Input type
Product 1
Mult. 1
MLIB_Mac4Sat_F32ssss
Product 2
Mult. 2
frac16_t
frac16_t
Result
type
Mult. 1
frac16_t
Description
Mult. 2
frac16_t
frac32_t
Addition of two 32-bit fractional
products (of two 16-bit fractional
multiplicands). The output is within
the range <-1 ; 1).
2.20.2 Declaration
The available MLIB_Mac4Sat functions have the following declarations:
frac32_t MLIB_Mac4Sat_F32ssss(frac16_t f16Add1Mult1, frac16_t f16Add1Mult2, frac16_t
f16Add2Mult1, frac16_t f16Add2Mult2)
2.20.3 Function use
The use of the MLIB_Mac4Sat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2;
void main(void)
{
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
}
=
=
=
=
FRAC16(-1.0);
FRAC16(-0.9);
FRAC16(0.8);
FRAC16(0.7);
/*
/*
/*
/*
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
=
=
=
=
-1.0 */
-0.9 */
0.8 */
0.7 */
/* f32Result = sat(f16Add1Mult1 * f16Add1Mult2 + f16Add2Mult1 * f16Add2Mult2) */
f32Result = MLIB_Mac4Sat_F32ssss(f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2);
2.21 MLIB_Mac4Rnd
The MLIB_Mac4Rnd functions return the rounded sum of two products of two pairs of
multiplicands. The round method is the round to nearest. The function does not saturate
the output. See the following equation:
MLIB User's Guide, Rev. 0, 10/2015
58
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Equation 18. Algorithm formula
2.21.1 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_Mac4Rnd function are shown in the following table.
Table 2-21. Function versions
Function name
Input type
Product 1
Mult. 1
Mult. 2
Product 2
Mult. 1
Result
type
Description
Mult. 2
MLIB_Mac4Rnd_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Addition of two 16-bit fractional products
(of two 16-bit fractional multiplicands),
rounded to the upper 16 bits. The output
is within the range <-1 ; 1).
MLIB_Mac4Rnd_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Addition of two 32-bit fractional products
(of two 32-bit fractional multiplicands),
rounded to the upper 32 bits. The output
is within the range <-1 ; 1).
2.21.2 Declaration
The available MLIB_Mac4Rnd functions have the following declarations:
frac16_t MLIB_Mac4Rnd_F16(frac16_t f16Add1Mult1, frac16_t f16Add1Mult2, frac16_t
f16Add2Mult1, frac16_t f16Add2Mult2)
frac32_t MLIB_Mac4Rnd_F32(frac32_t f32Add1Mult1, frac32_t f32Add1Mult2, frac32_t
f32Add2Mult1, frac32_t f32Add2Mult2)
2.21.3 Function use
The use of the MLIB_Mac4Rnd function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2;
void main(void)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
59
MLIB_Mac4RndSat
{
}
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
=
=
=
=
FRAC16(0.256);
FRAC16(-0.724);
FRAC16(0.365);
FRAC16(-0.25);
/*
/*
/*
/*
f16Add1Mult1
f16Add1Mult2
f16Add2Mult1
f16Add2Mult2
=
=
=
=
0.256 */
-0.724 */
0.365 */
-0.25 */
/* f16Result = round(f16Add1Mult1 * f16Add1Mult2 + f16Add2Mult1 * f16Add2Mult2) */
f16Result = MLIB_Mac4Rnd_F16(f16Add1Mult1, f16Add1Mult2, f16Add2Mult1, f16Add2Mult2);
2.22 MLIB_Mac4RndSat
The MLIB_Mac4RndSat functions return the rounded sum of two products of two pairs
of multiplicands. The round method is the round to nearest. The function saturates the
output. See the following equation:
Equation 19. Algorithm formula
2.22.1 Available versions
The 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_Mac4RndSat function are shown in the following
table.
Table 2-22. Function versions
Function name
Input type
Product 1
Mult. 1
Mult. 2
Product 2
Mult. 1
Result
type
Description
Mult. 2
MLIB_Mac4RndSat_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Addition of two 16-bit fractional
products (of two 16-bit fractional
multiplicands), rounded to the upper
16 bits. The output is within the
range <-1 ; 1).
MLIB_Mac4RndSat_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Addition of two 32-bit fractional
products (of two 32-bit fractional
multiplicands), rounded to the upper
32 bits. The output is within the
range <-1 ; 1).
MLIB User's Guide, Rev. 0, 10/2015
60
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.22.2 Declaration
The available MLIB_Mac4RndSat functions have the following declarations:
frac16_t MLIB_Mac4RndSat_F16(frac16_t f16Add1Mult1, frac16_t f16Add1Mult2, frac16_t
f16Add2Mult1, frac16_t f16Add2Mult2)
frac32_t MLIB_Mac4RndSat_F32(frac32_t f32Add1Mult1, frac32_t f32Add1Mult2, frac32_t
f32Add2Mult1, frac32_t f32Add2Mult2)
2.22.3 Function use
The use of the MLIB_Mac4RndSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Add1Mult1, f32Add1Mult2, f32Add2Mult1, f32Add2Mult2;
void main(void)
{
f32Add1Mult1
f32Add1Mult2
f32Add2Mult1
f32Add2Mult2
}
=
=
=
=
FRAC32(-1.0);
FRAC32(-0.9);
FRAC32(0.8);
FRAC32(0.7);
/*
/*
/*
/*
f32Add1Mult1
f32Add1Mult2
f32Add2Mult1
f32Add2Mult2
=
=
=
=
-1.0 */
-0.9 */
0.8 */
0.7 */
/* f32Result = sat(round(f32Add1Mult1 * f32Add1Mult2 + f32Add2Mult1 * f32Add2Mult2))*/
f32Result = MLIB_Mac4RndSat_F32(f32Add1Mult1, f32Add1Mult2, f32Add2Mult1, f32Add2Mult2);
2.23 MLIB_Msu
The MLIB_Msu functions return the fractional product of two multiplicands subtracted
from the input accumulator. The function does not saturate the output. See the following
equation:
Equation 20. Algorithm formula
2.23.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
61
MLIB_Msu
• 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Msu function are shown in the following table.
Table 2-23. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
Description
MLIB_Msu_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
subtracted from a 16-bit fractional accumulator. The
output is within the range <-1 ; 1).
MLIB_Msu_F32lss
frac32_t
frac16_t
frac16_t
frac32_t
The 32-bit fractional product (of two 16-bit fractional
multiplicands) is subracted from a 32-bit fractional
accumulator. The output is within the range <-1 ; 1).
MLIB_Msu_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
subtracted from a 32-bit fractional accumulator. The
output is within the range <-1 ; 1).
MLIB_Msu_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
subtracted from a 32-bit accumulator. The output
may be out of the range <-1 ; 1).
MLIB_Msu_FLT
float_t
float_t
float_t
float_t
The product (of two 32-bit single-point floating-point
multiplicands) is subtracted from a single-point
floating-point accumulator. The output is within the
full range.
2.23.2 Declaration
The available MLIB_Msu functions have the following declarations:
frac16_t MLIB_Msu_F16(frac16_t f16Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_Msu_F32lss(frac32_t f32Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_Msu_F32(frac32_t f32Accum, frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_Msu_A32ass(acc32_t a32Accum, frac16_t f16Mult1, frac16_t f16Mult2)
float_t MLIB_Msu_FLT(float_t fltAccum, float_t fltMult1, float_t fltMult2)
2.23.3 Function use
The use of the MLIB_Msu function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
62
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "mlib.h"
static acc32_t a32Accum, a32Result;
static frac16_t f16Mult1, f16Mult2;
void main(void)
{
a32Accum = ACC32(2.3);
f16Mult1 = FRAC16(0.1);
f16Mult2 = FRAC16(-0.2);
}
/* a32Accum = 2.3 */
/* f16Mult1 = 0.1 */
/* f16Mult2 = -0.2 */
/* a32Result = a32Accum - f16Mult1 * f16Mult2 */
a32Result = MLIB_Msu_A32ass(a32Accum, f16Mult1, f16Mult2);
2.24 MLIB_MsuSat
The MLIB_MsuSat functions return the fractional product of two multiplicands
subtracted from the input accumulator. The function saturates the output. See the
following equation:
Equation 21. Algorithm formula
2.24.1 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_MsuSat function are shown in the following table.
Table 2-24. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
Description
MLIB_MsuSat_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
subtracted from a 16-bit fractional accumulator.
The output is within the range <-1 ; 1).
MLIB_MsuSat_F32lss
frac32_t
frac16_t
frac16_t
frac32_t
The 32-bit fractional product (of two 16-bit
fractional multiplicands) is subtracted from a 32-bit
fractional accumulator. The output is within the
range <-1 ; 1).
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
63
MLIB_MsuRnd
Table 2-24. Function versions (continued)
Function name
Input type
Accum.
MLIB_MsuSat_F32
frac32_t
Mult. 1
frac32_t
Mult. 2
frac32_t
Result
type
frac32_t
Description
The upper 32-bit portion [32..63] of the fractional
product (of two 32-bit fractional multiplicands) is
subracted from a 32-bit fractional accumulator.
The output is within the range <-1 ; 1).
2.24.2 Declaration
The available MLIB_MsuSat functions have the following declarations:
frac16_t MLIB_MsuSat_F16(frac16_t f16Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuSat_F32lss(frac32_t f32Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuSat_F32(frac32_t f32Accum, frac32_t f32Mult1, frac32_t f32Mult2)
2.24.3 Function use
The use of the MLIB_MsuSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Accum, f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Accum = FRAC32(0.9);
f32Mult1 = FRAC32(-1.0);
f32Mult2 = FRAC32(0.2);
}
/* f32Accum = 0.9 */
/* f32Mult1 = -1.0 */
/* f32Mult2 = 0.2 */
/* f32Result = sat(f32Accum - f32Mult1 * f32Mult2) */
f32Result = MLIB_MsuSat_F32(f32Accum, f32Mult1, f32Mult2);
2.25 MLIB_MsuRnd
The MLIB_MsuRnd functions return the rounded fractional product of two multiplicands
subtracted from the input accumulator. The round method is the round to nearest. The
function does not saturate the output. See the following equation:
Equation 22. Algorithm formula
MLIB User's Guide, Rev. 0, 10/2015
64
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.25.1 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_MsuRnd function are shown in the following table.
Table 2-25. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
Description
MLIB_MsuRnd_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
subtracted from a 16-bit fractional accumulator.
The output is within the range <-1 ; 1).
MLIB_MsuRnd_F32lls
frac32_t
frac32_t
frac16_t
frac32_t
The fractional product (of a 32-bit and 16-bit
fractional multiplicands), rounded to the upper
32 bits [16..48], is subtracted from a 32-bit
fractional accumulator. The output is within the
range <-1 ; 1).
MLIB_MsuRnd_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 subtracted from a 32-bit fractional
accumulator. The output is within the range <-1 ;
1).
MLIB_MsuRnd_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 subtracted from a 32-bit accumulator.
The output may be out of the range <-1 ; 1).
2.25.2 Declaration
The available MLIB_MsuRnd functions have the following declarations:
frac16_t MLIB_MsuRnd_F16(frac16_t f16Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuRnd_F32lls(frac32_t f32Accum, frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuRnd_F32(frac32_t f32Accum, frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MsuRnd_A32ass(acc32_t a32Accum, frac16_t f16Mult1, frac16_t f16Mult2)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
65
MLIB_MsuRndSat
2.25.3 Function use
The use of the MLIB_MsuRnd function is shown in the following example:
#include "mlib.h"
static frac16_t f16Accum, f16Mult1, f16Mult2, f16Result;
void main(void)
{
f16Accum = FRAC16(0.3);
f16Mult1 = FRAC16(0.1);
f16Mult2 = FRAC16(-0.2);
}
/* f16Accum = 0.3 */
/* f16Mult1 = 0.1 */
/* f16Mult2 = -0.2 */
/* f16Result = round(f16Accum - f16Mult1 * f16Mult2) */
f16Result = MLIB_MsuRnd_F16(f16Accum, f16Mult1, f16Mult2);
2.26 MLIB_MsuRndSat
The MLIB_MsuRndSat functions return the rounded fractional product of two
multiplicands subtracted from the input accumulator. The round method is the round to
nearest. The function saturates the output. See the following equation:
Equation 23. Algorithm formula
2.26.1 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.
MLIB User's Guide, Rev. 0, 10/2015
66
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_MsuRndSat function are shown in the following
table.
Table 2-26. Function versions
Function name
Input type
Accum.
Mult. 1
Mult. 2
Result
type
Description
MLIB_MsuRndSat_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 subtracted from a 16-bit fractional
accumulator. The output is within the range
<-1 ; 1).
MLIB_MsuRndSat_F32lls
frac32_t
frac32_t
frac16_t
frac32_t
The fractional product (of a 32-bit and 16-bit
fractional multiplicands), rounded to the upper
32 bits [16..48], is subtracted from a 32-bit
fractional accumulator. The output is within
the range <-1 ; 1).
MLIB_MsuRndSat_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 subtracted from a 32-bit fractional
accumulator. The output is within the range
<-1 ; 1).
2.26.2 Declaration
The available MLIB_MsuRndSat functions have the following declarations:
frac16_t MLIB_MsuRndSat_F16(frac16_t f16Accum, frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuRndSat_F32lls(frac32_t f32Accum, frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MsuRndSat_F32(frac32_t f32Accum, frac32_t f32Mult1, frac32_t f32Mult2)
2.26.3 Function use
The use of the MLIB_MsuRndSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Accum, f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Accum = FRAC32(0.3);
f32Mult1 = FRAC32(0.1);
f32Mult2 = FRAC32(-0.2);
}
/* f32Accum = 0.3 */
/* f32Mult1 = 0.1 */
/* f32Mult2 = -0.2 */
/* f32Result = sat(round(f32Accum - f32Mult1 * f32Mult2)) */
f32Result = MLIB_MsuRndSat_F32(f32Accum, f32Mult1, f32Mult2);
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
67
MLIB_Msu4
2.27 MLIB_Msu4
The MLIB_Msu4 functions return the subtraction of the products of two multiplicands.
The function does not saturate the output. See the following equation:
Equation 24. Algorithm formula
2.27.1 Available versions
The 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Msu4 function are shown in the following table.
Table 2-27. Function versions
Function name
Input type
Minuend product
Mult. 1
Mult. 2
Subtrahend product
Mult. 1
Result
type
Description
Mult. 2
MLIB_Msu4_F32ssss
frac16_t
frac16_t
frac16_t
frac16_t
frac32_t
Subtraction of two 32-bit
fractional products (of two 16-bit
fractional multiplicands). The
output is within the range <-1 ;
1).
MLIB_Msu4_FLT
float_t
float_t
float_t
float_t
float_t
Subtraction of two 32-bit singlepoint floating-point products (of
two 32-bit single-point floatingpoint multiplicands). The output
is within the full range.
2.27.2 Declaration
The available MLIB_Msu4 functions have the following declarations:
frac32_t MLIB_Msu4_F32ssss(frac16_t f16MinMult1, frac16_t f16MinMult2, frac16_t f16SubMult1,
frac16_t f16SubMult2)
float_t MLIB_Msu4_FLT(float_t fltMinMult1, float_t fltMinMult2, float_t fltSubMult1, float_t
fltSubMult2)
MLIB User's Guide, Rev. 0, 10/2015
68
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.27.3 Function use
The use of the MLIB_Msu4 function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2;
void main(void)
{
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
}
=
=
=
=
FRAC16(0.2);
FRAC16(-0.7);
FRAC16(0.3);
FRAC16(-0.25);
/*
/*
/*
/*
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
=
=
=
=
0.2 */
-0.7 */
0.3 */
-0.25 */
/* f32Result = f16MinMult1 * f16MinMult2 - f16SubMult1 * f16SubMult2 */
f32Result = MLIB_Msu4_F32ssss(f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2);
2.28 MLIB_Msu4Sat
The MLIB_Msu4Sat functions return the subtraction of the products of two
multiplicands. The function saturates the output. See the following equation:
Equation 25. Algorithm formula
2.28.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
69
MLIB_Msu4Rnd
The available versions of the MLIB_Msu4Sat function are shown in the following table.
Table 2-28. Function versions
Function name
Input type
Minuend product
Mult. 1
MLIB_Msu4Sat_F32ssss
Subtrahend product
Mult. 2
frac16_t
frac16_t
Result
type
Mult. 1
frac16_t
Description
Mult. 2
frac16_t
frac32_t
Subtraction of two 32-bit
fractional products (of two
16-bit fractional
multiplicands). The output is
within the range <-1 ; 1).
2.28.2 Declaration
The available MLIB_Msu4Sat functions have the following declarations:
frac32_t MLIB_Msu4Sat_F32ssss(frac16_t f16MinMult1, frac16_t f16MinMult2, frac16_t
f16SubMult1, frac16_t f16SubMult2)
2.28.3 Function use
The use of the MLIB_Msu4Sat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2;
void main(void)
{
f16MinMult1 =
f16MinMult2 =
f16SubMult1 =
f16SubMult2 =
}
FRAC16(0.8);
FRAC16(-0.9);
FRAC16(0.7);
FRAC16(0.9);
/*
/*
/*
/*
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
=
=
=
=
0.8 */
-0.9 */
0.7 */
0.9 */
/* f32Result = sat(f16MinMult1 * f16MinMult2 - f16SubMult1 * f16SubMult2) */
f32Result = MLIB_Msu4Sat_F32ssss(f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2);
2.29 MLIB_Msu4Rnd
The MLIB_Msu4Rnd functions return the rounded subtraction of two products of two
pairs of multiplicands. The round method is the round to nearest. The function does not
saturate the output. See the following equation:
MLIB User's Guide, Rev. 0, 10/2015
70
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Equation 26. Algorithm formula
2.29.1 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_Msu4Rnd function are shown in the following table.
Table 2-29. Function versions
Function name
Input type
Minuend product
Mult. 1
Mult. 2
Subtrahend product
Mult. 1
Result
type
Description
Mult. 2
MLIB_Msu4Rnd_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Subtraction of two 16-bit
fractional products (of two 16-bit
fractional multiplicands), rounded
to the upper 16 bits. The output is
within the range <-1 ; 1).
MLIB_Msu4Rnd_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Subtraction of two 32-bit
fractional products (of two 32-bit
fractional multiplicands), rounded
to the upper 32 bits. The output is
within the range <-1 ; 1).
2.29.2 Declaration
The available MLIB_Msu4Rnd functions have the following declarations:
frac16_t
frac16_t
frac32_t
frac32_t
MLIB_Msu4Rnd_F16(frac16_t f16MinMult1, frac16_t f16MinMult2, frac16_t f16SubMult1,
f16SubMult2)
MLIB_Msu4Rnd_F32(frac32_t f32MinMult1, frac32_t f32MinMult2, frac32_t f32SubMult1,
f32SubMult2)
2.29.3 Function use
The use of the MLIB_Msu4Rnd function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2;
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
71
MLIB_Msu4RndSat
void main(void)
{
f16MinMult1 =
f16MinMult2 =
f16SubMult1 =
f16SubMult2 =
}
FRAC16(0.256);
FRAC16(-0.724);
FRAC16(0.365);
FRAC16(-0.25);
/*
/*
/*
/*
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
=
=
=
=
0.256 */
-0.724*/
0.365 */
-0.25 */
/* f32Result = round(f16MinMult1 * f16MinMult2 - f16SubMult1 * f16SubMult2) */
f16Result = MLIB_Msu4Rnd_F16(f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2);
2.30 MLIB_Msu4RndSat
The MLIB_Msu4RndSat functions return the rounded subtraction of two products of two
pairs of multiplicands. The round method is the round to nearest. The function saturates
the output. See the following equation:
Equation 27. Algorithm formula
2.30.1 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_Msu4RndSat function are shown in the following
table.
Table 2-30. Function versions
Function name
Input type
Minuend product
Mult. 1
Mult. 2
Subtrahend product
Mult. 1
Result
type
Description
Mult. 2
MLIB_Msu4RndSat_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Subtraction of two 16-bit
fractional products (of two 16bit fractional multiplicands),
rounded to the upper 16 bits.
The output is within the range
<-1 ; 1).
MLIB_Msu4RndSat_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Subtraction of two 32-bit
fractional products (of two 32bit fractional multiplicands),
MLIB User's Guide, Rev. 0, 10/2015
72
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Table 2-30. Function versions
Function name
Input type
Minuend product
Mult. 1
Subtrahend product
Mult. 2
Mult. 1
Result
type
Description
Mult. 2
rounded to the upper 32 bits.
The output is within the range
<-1 ; 1).
2.30.2 Declaration
The available MLIB_Msu4RndSat functions have the following declarations:
frac16_t MLIB_Msu4RndSat_F16(frac16_t f16MinMult1, frac16_t f16MinMult2, frac16_t
f16SubMult1, frac16_t f16SubMult2)
frac32_t MLIB_Msu4RndSat_F32(frac32_t f32MinMult1, frac32_t f32MinMult2, frac32_t
f32SubMult1, frac32_t f32SubMult2)
2.30.3 Function use
The use of the MLIB_Msu4RndSat function is shown in the following example:
#include "mlib.h"
static frac32_t ;
static frac16_t f16Result, f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2;
void main(void)
{
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
}
=
=
=
=
FRAC16(0.8);
FRAC16(-0.9);
FRAC16(0.7);
FRAC16(0.9);
/*
/*
/*
/*
f16MinMult1
f16MinMult2
f16SubMult1
f16SubMult2
=
=
=
=
0.8 */
-0.9 */
0.7 */
0.9 */
/* f16Result = sat(round(f16MinMult1 * f16MinMult2 - f16SubMult1 * f16SubMult2)) */
f16Result = MLIB_Msu4RndSat_F16(f16MinMult1, f16MinMult2, f16SubMult1, f16SubMult2);
2.31 MLIB_Mul
The MLIB_Mul functions return the product of two multiplicands. The function does not
saturate the output. See the following equation:
Equation 28. Algorithm formula
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
73
MLIB_Mul
2.31.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
The result may overflow.
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may overflow.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1 ; 1). The result may overflow.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Mul function are shown in the following table:
Table 2-31. Function versions
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_Mul_F16
frac16_t
frac16_t
frac16_t
Product of two 16-bit fractional multiplicands; the output are the
upper 16 bits of the results [16..31]. The output is within the range
<-1 ; 1).
MLIB_Mul_F16as
acc32_t
frac16_t
frac16_t
Product of a 32-bit accumulator and a 16-bit fractional multiplicand;
the output is a 16-bit fractional portion, which has the upper 16 bits
of the fractional value of the result [16..31]. The output is within the
range <-1 ; 1).
MLIB_Mul_F32ss
frac16_t
frac16_t
frac32_t
Product of two 16-bit fractional multiplicands; the result is a 32-bit
fractional value. The output is within the range <-1 ; 1).
MLIB_Mul_F32
frac32_t
frac32_t
frac32_t
Product of two 32-bit fractional multiplicands; the output are the
upper 32 bits of the results [16..31]. The output is within the range
<-1 ; 1).
MLIB_Mul_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the output is a 32bit accumulator, which has the upper mid bits of the result [16..47].
The output is within the range <-65536.0 ; 65536.0).
MLIB_Mul_FLT
float_t
float_t
float_t
Product of two 32-bit single precision floating-point multiplicands.
The output is within the full range.
2.31.2 Declaration
The available MLIB_Mul functions have the following declarations:
MLIB User's Guide, Rev. 0, 10/2015
74
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
frac16_t MLIB_Mul_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_Mul_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_Mul_F32ss(frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_Mul_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_Mul_A32(acc32_t a32Mult1, acc32_t a32Mult1)
float_t MLIB_Mul_FLT(float_t fltMult1, float_t fltMult2)
2.31.3 Function use
The use of the MLIB_Mul function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f32Mult1, f16Mult2;
void main(void)
{
f16Mult1 = FRAC16(0.4);
f16Mult2 = FRAC16(-0.2);
}
/* f16Mult1 = 0.4 */
/* f16Mult2 = -0.2 */
/* f32Result = f16Mult1 * f16Mult2 */
f32Result = MLIB_Mul_F32ss(f16Mult1, f16Mult2);
2.32 MLIB_MulSat
The MLIB_MulSat functions return the product of two multiplicands. The function
saturates the output. See the following equation:
Equation 29. Algorithm formula
2.32.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
The result may saturate.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
75
MLIB_MulSat
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may saturate.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1;1). The result may overflow.
The available versions of the MLIB_MulSat function are shown in the following table:
Table 2-32. Function versions
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MulSat_F16
frac16_t
frac16_t
frac16_t
Product of two 16-bit fractional multiplicands; the output is the
upper 16 bits of the results [16..31]. The output is within the
range <-1 ; 1).
MLIB_MulSat_F16as
acc32_t
frac16_t
frac16_t
Product of a 32-bit accumulator and a 16-bit fractional
multiplicand; the output is a 16-bit fractional value, which has
the upper 16 bits of the fractional portion of the result [16..31].
The output is within the range <-1 ; 1).
MLIB_MulSat_F32ss
frac16_t
frac16_t
frac32_t
Product of two 16-bit fractional multiplicands; the result is a 32bit fractional value. The output is within the range <-1 ; 1).
MLIB_MulSat_F32
frac32_t
frac32_t
frac32_t
Product of two 32-bit fractional multiplicands; the output are the
upper 32 bits of the results [16..31]. The output is within the
range <-1 ; 1).
MLIB_MulSat_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the output is a
32-bit accumulator, which has the mid bits of the result [16..47].
The output is within the range <-65536.0 ; 65536.0).
2.32.2 Declaration
The available MLIB_MulSat functions have the following declarations:
frac16_t MLIB_MulSat_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_MulSat_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_MulSat_F32ss(frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MulSat_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MulSat_A32(acc32_t a32Mult1, acc32_t a32Mult1)
2.32.3 Function use
The use of the MLIB_MulSat function is shown in the following example:
#include "mlib.h"
static acc32_t a32Accum;
static frac16_t f16Mult, f16Result;
MLIB User's Guide, Rev. 0, 10/2015
76
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
void main(void)
{
a32Accum = ACC32(-5.5);
f16Mult = FRAC16(0.3);
}
/* a32Accum = -5.5 */
/* f16Mult = 0.3 */
/* f16Result = sat(a32Accum * f16Mult) */
f16Result = MLIB_MulSat_F16as(a32Accum, f16Mult);
2.33 MLIB_MulNeg
The MLIB_MulNeg functions return the negative product of two multiplicands. The
function does not saturate the output. See the following equation:
Equation 30. Algorithm formula
2.33.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may overflow.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1;1). The result may overflow.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_MulNeg function are shown in the following table.
Table 2-33. Function versions
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MuNegl_F16
frac16_t
frac16_t
frac16_t
Negative product of two 16-bit fractional multiplicands; the
output are the upper 16 bits of the results [16..31]. The output
is within the range <-1 ; 1).
MLIB_MulNeg_F16as
acc32_t
frac16_t
frac16_t
Negative product of a 32-bit accumulator and a 16-bit fractional
multiplicand; the output is a 16-bit fractional value, which has
the upper 16 bits of the fractional portion of the result [16..31].
The output is within the range <-1 ; 1).
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
77
MLIB_MulRnd
Table 2-33. Function versions (continued)
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MulNeg_F32ss
frac16_t
frac16_t
frac32_t
Negative product of two 16-bit fractional multiplicands; the
result is a 32-bit fractional value. The output is within the range
<-1 ; 1).
MLIB_MulNeg_F32
frac32_t
frac32_t
frac32_t
Negative product of two 32-bit fractional multiplicands; the
output are the upper 32 bits of the results [16..31]. The output
is within the range <-1 ; 1).
MLIB_MulNeg_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the output is a
32-bit accumulator, which has the mid bits of the result
[16..47]. The output is within the range <-65536.0 ; 65536.0).
MLIB_MulNeg_FLT
float_t
float_t
float_t
Negative product of two 32-bit single precision floating-point
multiplicands. The output is within the full range.
2.33.2 Declaration
The available MLIB_MulNeg functions have the following declarations:
frac16_t MLIB_MulNeg_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_MulNeg_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_MulNeg_F32ss(frac16_t f16Mult1, frac16_t f16Mult2)
frac32_t MLIB_MulNeg_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MulNeg_A32(acc32_t a32Mult1, acc32_t a32Mult1)
float_t MLIB_MulNeg_FLT(float_t fltMult1, float_t fltMult2)
2.33.3 Function use
The use of the MLIB_MulNeg function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result;
static frac16_t f16Mult1, f16Mult2;
void main(void)
{
f16Mult1 = FRAC16(0.5);
f16Mult2 = FRAC16(-0.3);
}
/* f16Mult1 = 0.5 */
/* f16Mult2 = -0.3 */
/* f32Result = f16Mult1 * (-f16Mult2) */
f32Result = MLIB_MulNeg_F32ss(f16Mult1, f16Mult2);
2.34 MLIB_MulRnd
MLIB User's Guide, Rev. 0, 10/2015
78
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The MLIB_MulRnd functions return the rounded product of two multiplicands. The
round method is the round to nearest. The function does not saturate the output. See the
following equation:
Equation 31. Algorithm formula
2.34.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
The result may overflow.
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may overflow.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1 ; 1). The result may overflow.
The available versions of the MLIB_MulRnd function are shown in the following table:
Table 2-34. Function versions
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MulRnd_F16
frac16_t
frac16_t
frac16_t
Product of two 16-bit fractional multiplicands; the output is
rounded to the upper 16 bits of the results [16..31]. The output
is within the range <-1 ; 1).
MLIB_MulRnd_F16as
acc32_t
frac16_t
frac16_t
Product of a 32-bit accumulator and a 16-bit fractional
multiplicand; the output is a 16-bit fractional value, which is
rounded to the upper 16 bits of the fractional portion of the
result [16..31]. The output is within the range <-1 ; 1).
MLIB_MulRnd_F32ls
frac32_t
frac16_t
frac32_t
Product of a 32-bit and a 16-bit fractional multiplicand; the
output is rounded to the upper 32 bits of the fractional portion
of the result [16..47]. The output is within the range <-1 ; 1).
MLIB_MulRnd_F32
frac32_t
frac32_t
frac32_t
Product of two 32-bit fractional multiplicands; the output is
rounded to the upper 32 bits of the results [16..31]. The output
is within the range <-1 ; 1).
MLIB_MulRnd_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the output is
rounded to the middle bits of the result [16..47]. The output is
within the range <-65536.0 ; 65536.0).
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
79
MLIB_MulRndSat
2.34.2 Declaration
The available MLIB_MulRnd functions have the following declarations:
frac16_t MLIB_MulRnd_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_MulRnd_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_MulRnd_F32ls(frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MulRnd_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MulRnd_A32(acc32_t a32Mult1, acc32_t a32Mult1)
2.34.3 Function use
The use of the MLIB_MulRnd function is shown in the following example:
#include "mlib.h"
static frac32_t f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Mult1 = FRAC32(0.5);
f32Mult2 = FRAC32(-0.24564);
}
/* f32Mult1 = 0.5 */
/* f32Mult2 = -0.24564 */
/* f32Result = round(f32Mult1 * f32Mult2) */
f32Result = MLIB_MulRnd_F32(f32Mult1, f32Mult2);
2.35 MLIB_MulRndSat
The MLIB_MulRndSat functions return the rounded product of two multiplicands. The
round method is the round to nearest. The function saturates the output. See the following
equation:
Equation 32. Algorithm formula
2.35.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
The result may saturate.
MLIB User's Guide, Rev. 0, 10/2015
80
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may saturate.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1 ; 1). The result may overflow.
The available versions of the MLIB_MulRndSat function are shown in the following
table:
Table 2-35. Function versions
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MulRndSat_F16
frac16_t
frac16_t
frac16_t
Product of two 16-bit fractional multiplicands; the output is
rounded to the upper 16 bits of the results [16..31]. The
output is within the range <-1 ; 1).
MLIB_MulRndSat_F16as
acc32_t
frac16_t
frac16_t
Product of a 32-bit accumulator and a 16-bit fractional
multiplicand; the output is a 16-bit fractional value, which is
rounded to the upper 16 bits of the fractional portion of the
result [16..31]. The output is within the range <-1 ; 1).
MLIB_MulRndSat_F32ls
frac32_t
frac16_t
frac32_t
Product of a 32-bit multiplicand and a 16-bit fractional
multiplicand; the output is rounded to the upper 32 bits of
the fractional portion of the result [16..47]. The output is
within the range <-1 ; 1).
MLIB_MulRndSat_F32
frac32_t
frac32_t
frac32_t
Product of two 32-bit fractional multiplicands; the output is
rounded to the upper 32 bits of the results [16..31]. The
output is within the range <-1 ; 1).
MLIB_MulRndSat_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the output
is rounded to the the mid bits of the result [16..47]. The
output is within the range <-65536.0 ; 65536.0).
2.35.2 Declaration
The available MLIB_MulRndSat functions have the following declarations:
frac16_t MLIB_MulRndSat_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_MulRndSat_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_MulRndSat_F32ls(frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MulRndSat_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MulRndSat_A32(acc32_t a32Mult1, acc32_t a32Mult1)
2.35.3 Function use
The use of the MLIB_MulRndSat function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
81
MLIB_MulNegRnd
#include "mlib.h"
static frac32_t f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Mult1 = FRAC32(-1.0);
f32Mult2 = FRAC32(-1.0);
}
/* f32Mult1 = -1.0 */
/* f32Mult2 = -1.0 */
/* f32Result = sat(round(f32Mult1 * f32Mult2))*/
f32Result = MLIB_MulRndSat_F32(f32Mult1, f32Mult2);
2.36 MLIB_MulNegRnd
The MLIB_MulNegRnd functions return the rounded negative product of two
multiplicands. The round method is the round to nearest. The function does not saturate
the output. See the following equation:
Equation 33. Algorithm formula
2.36.1 Available versions
This function is available in the following versions:
• Fractional output with fractional inputs - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The inputs are the fractional values only.
• Fractional output with mixed inputs - the output is the fractional portion of the result;
the result is within the range <-1 ; 1). The inputs are the accumulator and fractional
values. The result may overflow.
• Accumulator output - the output is the accumulator type where the result can be out
of the range <-1 ; 1). The result may overflow.
The available versions of the MLIB_MulNegRnd function are shown in the following
table:
Table 2-36. Function versions
Function name
Input type
Mult. 1
MLIB_MulNegRnd_F16
frac16_t
Mult. 2
frac16_t
Result
type
frac16_t
Description
Negative product of two 16-bit fractional multiplicands; the
output is rounded to the upper 16 bits of the results
[16..31]. The output is within the range <-1 ; 1).
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
82
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Table 2-36. Function versions (continued)
Function name
Input type
Mult. 1
Mult. 2
Result
type
Description
MLIB_MulNegRnd_F16as
acc32_t
frac16_t
frac16_t
Negative product of a 32-bit accumulator and a 16-bit
fractional multiplicand; the output is a 16-bit fractional
value, which is rounded to the upper 16 bits of the
fractional portion of the result [16..31]. The output is within
the range <-1 ; 1).
MLIB_MulNegRnd_F32ls
frac32_t
frac16_t
frac32_t
Negative product of a 32-bit fractional multiplicand and a
16-bit fractional multiplicand; the output is rounded to the
upper 32 bits of the fractional portion of the result [16..47].
The output is within the range <-1 ; 1).
MLIB_MulNegRnd_F32
frac32_t
frac32_t
frac32_t
Negative product of two 32-bit fractional multiplicands; the
output is rounded to the upper 32 bits of the results
[16..31]. The output is within the range <-1 ; 1).
MLIB_MulNegRnd_A32
acc32_t
acc32_t
acc32_t
Product of two 32-bit accumulator multiplicands; the
output is rounded to the the middle bits of the result
[16..47]. The output is within the range <-65536.0 ;
65536.0).
2.36.2 Declaration
The available MLIB_MulNegRnd functions have the following declarations:
frac16_t MLIB_MulNegRnd_F16(frac16_t f16Mult1, frac16_t f16Mult2)
frac16_t MLIB_MulNegRnd_F16as(acc32_t a32Accum, frac16_t f16Mult)
frac32_t MLIB_MulNegRnd_F32ls(frac32_t f32Mult1, frac16_t f16Mult2)
frac32_t MLIB_MulNegRnd_F32(frac32_t f32Mult1, frac32_t f32Mult2)
acc32_t MLIB_MulNegRnd_A32(acc32_t a32Mult1, acc32_t a32Mult1)
2.36.3 Function use
The use of the MLIB_MulNegRnd function is shown in the following example:
#include "mlib.h"
static frac32_t f32Mult1, f32Mult2, f32Result;
void main(void)
{
f32Mult1 = FRAC32(0.3);
f32Mult2 = FRAC32(-0.5);
}
/* f32Mult1 = 0.3 */
/* f32Mult2 = -0.5 */
/* f32Result = round(f32Mult1 * (-f32Mult2)) */
f32Result = MLIB_MulNegRnd_F32(f32Mult1, f32Mult2);
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
83
MLIB_Neg
2.37 MLIB_Neg
The MLIB_Neg functions return the negative value of the input. The function does not
saturate the output. See the following equation:
Equation 34. Algorithm formula
2.37.1 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Neg function are shown in the following table:
Table 2-37. Function versions
Function name
Input type
Result type
Description
MLIB_Neg_F16
frac16_t
frac16_t
Negative value of a 16-bit fractional value. The output is within the
range <-1 ; 1).
MLIB_Neg_F32
frac32_t
frac32_t
Negative value of a 32-bit fractional value. The output is within the
range <-1 ; 1).
MLIB_Neg_FLT
float_t
float_t
Negative value of a 32-bit single precision floating-point value. The
output is within the full range.
2.37.2 Declaration
The available MLIB_Neg functions have the following declarations:
frac16_t MLIB_Neg_F16(frac16_t f16Val)
frac32_t MLIB_Neg_F32(frac32_t f32Val)
float_t MLIB_Neg_FLT(float_t fltVal)
2.37.3 Function use
The use of the MLIB_Neg function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
84
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "mlib.h"
static frac32_t f32Val, f32Result;
void main(void)
{
f32Val = FRAC32(0.85);
}
/* f32Val = 0.85 */
/* f32Result = -f32Val */
f32Result = MLIB_Neg_F32(f32Val);
2.38 MLIB_NegSat
The MLIB_NegSat functions return the negative value of the input. The function
saturates the output. See the following equation:
Equation 35. Algorithm formula
2.38.1 Available versions
The 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_NegSat function are shown in the following table:
Table 2-38. Function versions
Function name
Input type
Result type
Description
MLIB_NegSat_F16
frac16_t
frac16_t
Negative value of a 16-bit value. The output is within the range <-1 ;
1).
MLIB_NegSat_F32
frac32_t
frac32_t
Negative value of a 32-bit value. The output is within the range <-1 ;
1).
2.38.2 Declaration
The available MLIB_NegSat functions have the following declarations:
frac16_t MLIB_NegSat_F16(frac16_t f16Val)
frac32_t MLIB_NegSat_F32(frac32_t f32Val)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
85
MLIB_Rcp
2.38.3 Function use
The use of the MLIB_NegSat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Val, f32Result;
void main(void)
{
f32Val = FRAC32(-1.0);
}
/* f32Val = -1.0*/
/* f32Result = sat(-f32Val) */
f32Result = MLIB_NegSat_F32(f32Val);
2.39 MLIB_Rcp
The MLIB_Rcp functions return the reciprocal value for the input value. The function
does not saturate the output. See the following equation:
Equation 36. Algorithm formula
2.39.1 Available versions
This function is available in the following versions:
• Accumulator output with fractional input - the output is the accumulator type, where
the absolute value of the result is greater than or equal to 1. The input is the fractional
type.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
MLIB User's Guide, Rev. 0, 10/2015
86
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_Rcp function are shown in the following table.
Table 2-39. Function versions
Function name
Input type
Result type
Description
MLIB_Rcp_A32s
frac16_t
acc32_t
Reciprocal for a 16-bit fractional value; the output is a 32-bit
accumulator value. The absolute value of the output is greater than or
equal to 1. The division is performed with 32-bit accuracy.
MLIB_Rcp1_A32s
frac16_t
acc32_t
Reciprocal for a 16-bit fractional value; the output is a 32-bit
accumulator value. The absolute value of the output is greater than or
equal to 1. Faster version, where the division is performed with 16-bit
accuracy.
MLIB_Rcp_FLT
float_t
float_t
Reciprocal for a 32-bit single precision floating-point value; the output
is a 32-bit single precision floating-point.
2.39.2 Declaration
The available MLIB_Rcp functions have the following declarations:
acc32_t MLIB_Rcp_A32s(frac16_t f16Denom)
acc32_t MLIB_Rcp1_A32s(frac16_t f16Denom)
float_t MLIB_Rcp_FLT(float_t fltDenom)
2.39.3 Function use
The use of the MLIB_Rcp function is shown in the following example:
#include "mlib.h"
static acc32_t a32Result;
static frac16_t f16Denom;
void main(void)
{
f16Denom = FRAC16(0.354);
}
/* f16Denom = 0.354 */
/* a32Result = 1/f16Denom */
a32Result = MLIB_Rcp1_A32s(f16Denom);
2.40 MLIB_Rcp1Q
The MLIB_Rcp1Q functions return the single quadrant reciprocal value for the input
value. The input value must be a nonnegative number, otherwise the function returns
undefined results. The function does not saturate the output. See the following equation:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
87
MLIB_Rcp1Q
Equation 37. Algorithm formula
2.40.1 Available versions
This function is available in the following versions:
• Accumulator output with fractional input - the output is the accumulator type, where
the result is greater than or equal to 1. The function is not defined for negative inputs.
The input is the fractional type.
The available versions of the MLIB_Rcp1Q function are shown in the following table.
Table 2-40. Function versions
Function name
Input type
Result type
Description
MLIB_Rcp1Q_A32s
frac16_t
acc32_t
Reciprocal for a nonnegative 16-bit fractional value; the output is a
positive 32-bit accumulator value. The output is greater than or
equal to 1. The division is performed with 32-bit accuracy.
MLIB_Rcp1Q1_A32s
frac16_t
acc32_t
Reciprocal for a nonnegative 16-bit fractional value; the output is a
positive 32-bit accumulator value. The output is greater than or
equal to 1. Faster version, where the division is performed with 16bit accuracy.
2.40.2 Declaration
The available MLIB_Rcp1Q functions have the following declarations:
acc32_t MLIB_Rcp1Q_A32s(frac16_t f16Denom)
acc32_t MLIB_Rcp1Q1_A32s(frac16_t f16Denom)
2.40.3 Function use
The use of the MLIB_Rcp1Q function is shown in the following example:
#include "mlib.h"
static acc32_t a32Result;
static frac16_t f16Denom;
void main(void)
{
f16Denom = FRAC16(0.354);
/* f16Denom = 0.354 */
MLIB User's Guide, Rev. 0, 10/2015
88
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
}
/* a32Result = 1/f16Denom */
a32Result = MLIB_Rcp1Q1_A32s(f16Denom);
2.41 MLIB_Rnd
The MLIB_Rnd functions round the input to the nearest value to meet the return type's
size. The function does not saturate the output. See the following equation:
Equation 38. Algorithm formula
2.41.1 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_Rnd function are shown in the following table.
Table 2-41. Function versions
Function name
MLIB_Rnd_F16l
Input type
frac32_t
Result type
frac16_t
Description
Rounding of a 32-bit fractional value to a 16-bit fractional value. The
output is within the range <-1 ; 1).
2.41.2 Declaration
The available MLIB_Rnd functions have the following declarations:
frac16_t MLIB_Rnd_F16l(frac32_t f32Val)
2.41.3 Function use
The use of the MLIB_Rnd function is shown in the following example:
#include "mlib.h"
static frac32_t f32Val;
static frac16_t f16Result;
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
89
MLIB_RndSat
void main(void)
{
f32Val = FRAC32(0.85);
}
/* f32Val = 0.85 */
/* f16Result = round(f32Val)*/
f16Result = MLIB_Rnd_F16l(f32Val);
2.42 MLIB_RndSat
The MLIB_RndSat functions round the input to the nearest value to meet the return type's
size. The function saturates the output. See the following equation:
Equation 39. Algorithm formula
2.42.1 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_RndSat function are shown in the following table.
Table 2-42. Function versions
Function name
MLIB_RndSat_F16l
Input type
frac32_t
Result type
frac16_t
Description
Rounding of a 32-bit fractional value to a 16-bit fractional value.
The output is within the range <-1 ; 1).
2.42.2 Declaration
The available MLIB_RndSat functions have the following declarations:
frac16_t MLIB_RndSat_F16l(frac32_t f32Val)
2.42.3 Function use
The use of the MLIB_RndSat function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
90
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "mlib.h"
static frac32_t f32Val;
static frac16_t f16Result;
void main(void)
{
f32Val = FRAC32(0.9997996);
}
/* f32Val = 0.9997996 */
/* f16Result = sat(round(f32Val)) */
f16Result = MLIB_RndSat_F16l(f32Val);
2.43 MLIB_Sat
The MLIB_Sat functions return the fractional portion of the accumulator input. The
output is saturated if necessary. See the following equation:
Equation 40. Algorithm formula
2.43.1 Available versions
This function is available in the following versions:
• Fractional output with accumulator input - the output is the fractional portion of the
result; the result is within the range <-1 ; 1). The result is saturated.
The available versions of the MLIB_Sat function are shown in the following table.
Table 2-43. Function versions
Function name
MLIB_Sat_F16a
Input type
acc32_t
Result type
frac16_t
Description
Saturation of a 32-bit accumulator value to a 16-bit fractional value. The
output is within the range <-1 ; 1).
2.43.2 Declaration
The available MLIB_Sat functions have the following declarations:
frac16_t MLIB_Sat_F16a(acc32_t a32Accum)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
91
MLIB_Sh1L
2.43.3 Function use
The use of the MLIB_Sat function is shown in the following example:
#include "mlib.h"
static acc32_t a32Accum;
static frac16_t f16Result;
void main(void)
{
a32Accum = ACC32(5.6);
}
/* a32Accum = 5.6 */
/* f16Result = sat(a32Accum) */
f16Result = MLIB_Sat_F16a(a32Accum);
2.44 MLIB_Sh1L
The MLIB_Sh1L functions return the arithmetically one-time-shifted value to the left.
The function does not saturate the output. See the following equation:
Equation 41. Algorithm formula
2.44.1 Available versions
The 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_Sh1L function are shown in the following table.
Table 2-44. Function versions
Function name
Input type
Result type
Description
MLIB_Sh1L_F16
frac16_t
frac16_t
Shift of a 16-bit fractional value by one time to the left. The output is
within the range <-1 ; 1).
MLIB_Sh1L_F32
frac32_t
frac32_t
Shift of a 32-bit fractional value by one time to the left. The output is
within the range <-1 ; 1).
MLIB User's Guide, Rev. 0, 10/2015
92
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.44.2 Declaration
The available MLIB_Sh1L functions have the following declarations:
frac16_t MLIB_Sh1L_F16(frac16_t f16Val)
frac32_t MLIB_Sh1L_F32(frac32_t f32Val)
2.44.3 Function use
The use of the MLIB_Sh1L function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Val;
void main(void)
{
f32Val = FRAC32(-0.354);
}
/* f32Val = -0.354 */
/* f32Result = f32Val << 1 */
f32Result = MLIB_Sh1L_F32(f32Val);
2.45 MLIB_Sh1LSat
The MLIB_Sh1LSat functions return the arithmetically one-time-shifted value to the left.
The function saturates the output. See the following equation:
Equation 42. Algorithm formula
2.45.1 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
93
MLIB_Sh1R
The available versions of the MLIB_Sh1LSat function are shown in the following table.
Table 2-45. Function versions
Function name
Input type
Result type
Description
MLIB_Sh1LSat_F16
frac16_t
frac16_t
Shift of a 16-bit fractional value by one time to the left. The output is
within the range <-1 ; 1).
MLIB_Sh1LSat_F32
frac32_t
frac32_t
Shift of a 32-bit fractional value by one time to the left. The output is
within the range <-1 ; 1).
2.45.2 Declaration
The available MLIB_Sh1LSat functions have the following declarations:
frac16_t MLIB_Sh1LSat_F16(frac16_t f16Val)
frac32_t MLIB_Sh1LSat_F32(frac32_t f32Val)
2.45.3 Function use
The use of the MLIB_Sh1LSat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Val;
void main(void)
{
f16Val = FRAC16(0.354);
}
/* f16Val = 0.354 */
/* f16Result = sat(f16Val << 1) */
f16Result = MLIB_Sh1LSat_F16(f16Val);
2.46 MLIB_Sh1R
The MLIB_Sh1R functions return the arithmetically one-time-shifted value to the right.
See the following equation:
Equation 43. Algorithm formula
MLIB User's Guide, Rev. 0, 10/2015
94
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.46.1 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.5 ; 0.5).
The available versions of the MLIB_Sh1R function are shown in the following table.
Table 2-46. Function versions
Function name
Input type
Result type
Description
MLIB_Sh1R_F16
frac16_t
frac16_t
Shift of a 16-bit fractional value by one time to the right. The output is
within the range <-0.5 ; 0.5).
MLIB_Sh1R_F32
frac32_t
frac32_t
Shift of a 32-bit fractional value by one time to the right. The output is
within the range <-0.5 ; 0.5).
2.46.2 Declaration
The available MLIB_Sh1R functions have the following declarations:
frac16_t MLIB_Sh1R_F16(frac16_t f16Val)
frac32_t MLIB_Sh1R_F32(frac32_t f32Val)
2.46.3 Function use
The use of the MLIB_Sh1R function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Val;
void main(void)
{
f32Val = FRAC32(-0.354);
}
/* f32Val = -0.354 */
/* f32Result = f32Val >> 1 */
f32Result = MLIB_Sh1R_F32(f32Val);
2.47 MLIB_ShL
The MLIB_ShL functions return the arithmetically shifted value to the left a specified
number of times. The function does not saturate the output. See the following equation:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
95
MLIB_ShL
Equation 44. Algorithm formula
2.47.1 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_ShL function are shown in the following table.
Table 2-47. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShL_F16
frac16_t
uint16_t
frac16_t
Shift of a 16-bit fractional value to the left by a number of times given
by the second argument; the shift is allowed within the range <0 ; 15>.
The output is within the range <-1 ; 1).
MLIB_ShL_F32
frac32_t
uint16_t
frac32_t
Shift of a 32-bit fractional value to the left by a number of times given
by the second argument; the shift is allowed within the range <0 ; 31>.
The output is within the range <-1 ; 1).
2.47.2 Declaration
The available MLIB_ShL functions have the following declarations:
frac16_t MLIB_ShL_F16(frac16_t f16Val, uint16_t u16Sh)
frac32_t MLIB_ShL_F32(frac32_t f32Val, uint16_t u16Sh)
2.47.3 Function use
The use of the MLIB_ShL function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Val;
static uint16_t u16Sh;
void main(void)
{
f16Val = FRAC16(-0.354);
u16Sh = 6;
/* f16Result =
/* f16Val = -0.354 */
/* u16Sh = 6 */
f16Val << u16Sh */
MLIB User's Guide, Rev. 0, 10/2015
96
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
}
f16Result = MLIB_ShL_F16(f16Val, u16Sh);
2.48 MLIB_ShLSat
The MLIB_ShLSat functions return the arithmetically shifted value to the left a specified
number of times. The function saturates the output. See the following equation:
Equation 45. Algorithm formula
2.48.1 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_ShLSat function are shown in the following table.
Table 2-48. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShLSat_F16
frac16_t
uint16_t
frac16_t
Shift of a 16-bit fractional value to the left by a number of times
given by the second argument; the shift is allowed within the
range <0 ; 15>. The output is within the range <-1 ; 1).
MLIB_ShLSat_F32
frac32_t
uint16_t
frac32_t
Shift of a 32-bit fractional value to the left by a number of times
given by the second argument; the shift is allowed within the
range <0 ; 31>. The output is within the range <-1 ; 1).
2.48.2 Declaration
The available MLIB_ShLSat functions have the following declarations:
frac16_t MLIB_ShLSat_F16(frac16_t f16Val, uint16_t u16Sh)
frac32_t MLIB_ShLSat_F32(frac32_t f32Val, uint16_t u16Sh)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
97
MLIB_ShR
2.48.3 Function use
The use of the MLIB_ShLSat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Val;
static uint16_t u16Sh;
void main(void)
{
f16Val = FRAC16(-0.003);
u16Sh = 6;
}
/* f16Val = -0.003 */
/* u16Sh = 6 */
/* f16Result = sat(f16Val << u16Sh) */
f16Result = MLIB_ShLSat_F16(f16Val, u16Sh);
2.49 MLIB_ShR
The MLIB_ShR functions return the arithmetically shifted value to the right a specified
number of times. See the following equation:
Equation 46. Algorithm formula
2.49.1 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_ShR function are shown in the following table.
Table 2-49. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShR_F16
frac16_t
uint16_t
frac16_t
Shift of a 16-bit fractional value to the right by a number of times
given by the second argument; the shift is allowed within the range
<0 ; 15>. The output is within the range <-1 ; 1).
MLIB_ShR_F32
frac32_t
uint16_t
frac32_t
Shift of a 32-bit fractional value to the right by a number of times
given by the second argument; the shift is allowed within the range
<0 ; 31>. The output is within the range <-1 ; 1).
MLIB User's Guide, Rev. 0, 10/2015
98
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.49.2 Declaration
The available MLIB_ShR functions have the following declarations:
frac16_t MLIB_ShR_F16(frac16_t f16Val, uint16_t u16Sh)
frac32_t MLIB_ShR_F32(frac32_t f32Val, uint16_t u16Sh)
2.49.3 Function use
The use of the MLIB_ShR function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Val;
static uint16_t u16Sh;
void main(void)
{
f16Val = FRAC32(-0.354);
u16Sh = 8;
}
/* f16Val = -0.354 */
/* u16Sh = 8 */
/* f16Result = f16Val >> u16Sh */
f16Result = MLIB_ShR_F16(f16Val, u16Sh);
2.50 MLIB_ShLBi
The MLIB_ShLBi functions return the arithmetically shifted value to the left a specified
number of times. If the number of shifts is positive, the shift is performed to the left; if
negative, to the right. The function does not saturate the output. See the following
equation:
Equation 47. Algorithm formula
2.50.1 Available versions
The 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.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
99
MLIB_ShLBiSat
The available versions of the MLIB_ShLBi function are shown in the following table.
Table 2-50. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShLBi_F16
frac16_t
int16_t
frac16_t
Bidirectional shift of a 16-bit fractional value to the left by a number
of times given by the second argument; if the second argument is
negative, the shift is performed to the right. The shift is allowed within
the range <-15 ; 15>. The output is within the range <-1 ; 1).
MLIB_ShLBi_F32
frac32_t
int16_t
frac32_t
Bidirectional shift of a 32-bit fractional value to the left by a number
of times given by the second argument; if the second argument is
negative, the shift is performed to the right. The shift is allowed within
the range <-31 ; 31>. The output is within the range <-1 ; 1).
2.50.2 Declaration
The available MLIB_ShLBi functions have the following declarations:
frac16_t MLIB_ShLBi_F16(frac16_t f16Val, int16_t i16Sh)
frac32_t MLIB_ShLBi_F32(frac32_t f32Val, int16_t i16Sh)
2.50.3 Function use
The use of the MLIB_ShLBi function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Val;
static int16_t i16Sh;
void main(void)
{
f32Val = FRAC32(-0.354);
i16Sh = -3;
}
/* f32Val = -0.354 */
/* i16Sh = -3 */
/* f32Result = f32Val << i16Sh */
f32Result = MLIB_ShLBi_F32(f32Val, i16Sh);
2.51 MLIB_ShLBiSat
MLIB User's Guide, Rev. 0, 10/2015
100
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The MLIB_ShLBiSat functions return the arithmetically shifted value to the left a
specified number of times. If the number of shifts is positive, the shift is performed to the
left; if negative, to the right. The function saturates the output. See the following
equation:
Equation 48. Algorithm formula
2.51.1 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_ShLBiSat function are shown in the following table.
Table 2-51. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShLBiSat_F16
frac16_t
int16_t
frac16_t
Bidirectional shift of a 16-bit fractional value to the left by a
number of times given by the second argument; if the second
argument is negative, the shift is performed to the right. The shift
is allowed within the range <-15 ; 15>. The output is within the
range <-1 ; 1).
MLIB_ShLBiSat_F32
frac32_t
int16_t
frac32_t
Bidirectional shift of a 32-bit fractional value to the left by a
number of times given by the second argument; if the second
argument is negative, the shift is performed to the right. The shift
is allowed within the range <-31 ; 31>. The output is within the
range <-1 ; 1).
2.51.2 Declaration
The available MLIB_ShLBiSat functions have the following declarations:
frac16_t MLIB_ShLBiSat_F16(frac16_t f16Val, int16_t i16Sh)
frac32_t MLIB_ShLBiSat_F32(frac32_t f32Val, int16_t i16Sh)
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
101
MLIB_ShRBi
2.51.3 Function use
The use of the MLIB_ShLBiSat function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Val;
static int16_t i16Sh;
void main(void)
{
f16Val = FRAC16(-0.354);
i16Sh = 14;
/* f16Val = -0.354 */
/* i16Sh = 14 */
/* f16Result = sat(f16Val << i16Sh) */
f16Result = MLIB_ShLBiSat_F16(f16Val, i16Sh);
}
2.52 MLIB_ShRBi
The MLIB_ShRBi functions return the arithmetically shifted value to the right a specified
number of times. If the number of shifts is positive, the shift is performed to the right; if
negative, to the left. The function does not saturate the output. See the following
equation:
Equation 49. Algorithm formula
2.52.1 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_ShRBi function are shown in the following table.
Table 2-52. Function versions
Function name
MLIB_ShRBi_F16
Input type
Value
Shift
frac16_t
int16_t
Result
type
frac16_t
Description
Bidirectional shift of a 16-bit fractional value to the right by a number
of times given by the second argument; if the second argument is
negative, the shift is performed to the left. The shift is allowed within
the range <-15 ; 15>. The output is within the range <-1 ; 1).
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
102
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Table 2-52. Function versions (continued)
Function name
MLIB_ShRBi_F32
Input type
Value
Shift
frac32_t
int16_t
Result
type
frac32_t
Description
Bidirectional shift of a 32-bit fractional value to the right by a number
of times given by the second argument; if the second argument is
negative, the shift is performed to the left. The shift is allowed within
the range <-31 ; 31>. The output is within the range <-1 ; 1).
2.52.2 Declaration
The available MLIB_ShRBi functions have the following declarations:
frac16_t MLIB_ShRBi_F16(frac16_t f16Val, int16_t i16Sh)
frac32_t MLIB_ShRBi_F32(frac32_t f32Val, int16_t i16Sh)
2.52.3 Function use
The use of the MLIB_ShRBi function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Val;
static int16_t i16Sh;
void main(void)
{
f32Val = FRAC32(0.354);
i16Sh = 8;
}
/* f32In = 0.354 */
/* i16Sh = 8 */
/* f32Result = f32Val >> i16Sh */
f32Result = MLIB_ShRBi_F32(f32Val, i16Sh);
2.53 MLIB_ShRBiSat
The MLIB_ShRBiSat functions return the arithmetically shifted value to the right a
specified number of times. If the number of shifts is positive, the shift is performed to the
right; if negative, to the left. The function saturates the output. See the following
equation:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
103
MLIB_ShRBiSat
Equation 50. Algorithm formula
2.53.1 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_ShRBiSat function are shown in the following table.
Table 2-53. Function versions
Function name
Input type
Result
type
Description
Value
Shift
MLIB_ShRBiSat_F16
frac16_t
int16_t
frac16_t
Bidirectional shift of a 16-bit fractional value to the right by a
number of times given by the second argument; if the second
argument is negative, the shift is performed to the left. The shift
is allowed within the range <-15 ; 15>. The output is within the
range <-1 ; 1).
MLIB_ShRBiSat_F32
frac32_t
int16_t
frac32_t
Bidirectional shift of a 32-bit fractional value to the right by a
number of times given by the second argument; if the second
argument is negative, the shift is performed to the left. The shift
is allowed within the range <-31 ; 31>. The output is within the
range <-1 ; 1).
2.53.2 Declaration
The available MLIB_ShRBiSat functions have the following declarations:
frac16_t MLIB_ShRBiSat_F16(frac16_t f16Val, int16_t i16Sh)
frac32_t MLIB_ShRBiSat_F32(frac32_t f32Val, int16_t i16Sh)
2.53.3 Function use
The use of the MLIB_ShRBiSat function is shown in the following example:
include "mlib.h"
static frac32_t f32Result, f32Val;
MLIB User's Guide, Rev. 0, 10/2015
104
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
static int16_t i16Sh;
void main(void)
{
f32Val = FRAC32(-0.354);
i16Sh = 13;
}
/* f32Val = -0.354 */
/* i16Sh = 13 */
/* f32Result = sat(f32Val >> i16Sh) */
f32Result = MLIB_ShRBiSat_F32(f32Val, i16Sh);
2.54 MLIB_Sign
The MLIB_Sign functions return the sign of the input. See the following equation:
Equation 51. Algorithm formula
2.54.1 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).
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Sign function are shown in the following table.
Table 2-54. Function versions
Function name
Input type
Result type
Description
MLIB_Sign_F16
frac16_t
frac16_t
Sign of a 16-bit fractional value. The output is within the range <-1 ; 1).
MLIB_Sign_F32
frac32_t
frac32_t
Sign of a 32-bit fractional value. The output is within the range <-1 ; 1).
MLIB_Sign_FLT
float_t
float_t
Sign of a 32-bit single precision floating-point value. The output is
within the full range.
2.54.2 Declaration
The available MLIB_Sign functions have the following declarations:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
105
MLIB_Sub
frac16_t MLIB_Sign_F16(frac16_t f16Val)
frac32_t MLIB_Sign_F32(frac32_t f32Val)
float_t MLIB_Sign_FLT(float_t fltVal)
2.54.3 Function use
The use of the MLIB_Sign function is shown in the following example:
#include "mlib.h"
static frac32_t f32In, f32Result;
void main(void)
{
f32In = FRAC32(-0.95);
}
/* f32In = -0.95 */
/* f32Result = sign(f32In)*/
f32Result = MLIB_Sign_F32(f32In);
2.55 MLIB_Sub
The MLIB_Sub functions subtract the subtrahend from the minuend. The function does
not saturate the output. See the following equation:
Equation 52. Algorithm formula
2.55.1 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 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
MLIB User's Guide, Rev. 0, 10/2015
106
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_Sub function are shown in the following table.
Table 2-55. Function versions
Function name
Input type
Minuend
Subtrahend
Result
type
Description
MLIB_Sub_F16
frac16_t
frac16_t
frac16_t
Subtraction of a 16-bit fractional subtrahend from a 16-bit
fractional minuend. The output is within the range <-1 ; 1).
MLIB_Sub_F32
frac32_t
frac32_t
frac32_t
Subtraction of a 32-bit fractional subtrahend from a 32-bit
fractional minuend. The output is within the range <-1 ; 1).
MLIB_Sub_A32ss
frac16_t
frac16_t
acc32_t
Subtraction of a 16-bit fractional subtrahend from a 16-bit
fractional minuend; the result is a 32-bit accumulator. The
output may be out of the range <-1 ; 1).
MLIB_Sub_A32as
acc32_t
frac16_t
acc32_t
Subtraction of a 16-bit fractional subtrahend from a 32-bit
accumulator. The output may be out of the range <-1 ; 1).
MLIB_Sub_FLT
float_t
float_t
float_t
Subtraction of a 32-bit single precision floating-point
subtrahend from a 32-bit single precision floating-point
minuend. The output is within the full range.
2.55.2 Declaration
The available MLIB_Sub functions have the following declarations:
frac16_t MLIB_Sub_F16(frac16_t f16Min, frac16_t f16Sub)
frac32_t MLIB_Sub_F32(frac32_t f32Min, frac32_t f32Sub)
acc32_t MLIB_Sub_A32ss(frac16_t f16Min, frac16_t f16Sub)
acc32_t MLIB_Sub_A32as(acc32_t a32Accum, frac16_t f16Sub)
float_t MLIB_Sub_FLT(float_t fltMin, float_t fltSub)
2.55.3 Function use
The use of the MLIB_Sub function is shown in the following example:
#include "mlib.h"
static acc32_t a32Accum, a32Result;
static frac16_t f16Sub;
void main(void)
{
a32Accum = ACC32(4.5);
f16Sub = FRAC16(0.4);
}
/* a32Accum = 4.5 */
/* f16Sub = 0.4 */
/* a32Result = a32Accum - f16Sub */
a32Result = MLIB_Sub_A32as(a32Accum,f16Sub);
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
107
MLIB_SubSat
2.56 MLIB_SubSat
The MLIB_SubSat functions subtract the subtrahend from the minuend. The function
saturates the output. See the following equation:
Equation 53. Algorithm formula
2.56.1 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_SubSat function are shown in the following table.
Table 2-56. Function versions
Function name
Input type
Minuend
Subtrahend
Result
type
Description
MLIB_SubSat_F16
frac16_t
frac16_t
frac16_t
Subtraction of a 16-bit fractional subtrahend from a 16-bit
fractional minuend. The output is within the range <-1 ; 1).
MLIB_SubSat_F32
frac32_t
frac32_t
frac32_t
Subtraction of a 32-bit fractional subtrahend from a 32-bit
fractional minuend. The output is within the range <-1 ; 1).
2.56.2 Declaration
The available MLIB_SubSat functions have the following declarations:
frac16_t MLIB_SubSat_F16(frac16_t f16Min, frac16_t f16Sub)
frac32_t MLIB_SubSat_F32(frac32_t f32Min, frac32_t f32Sub)
2.56.3 Function use
The use of the MLIB_SubSat function is shown in the following example:
MLIB User's Guide, Rev. 0, 10/2015
108
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "mlib.h"
static frac32_t f32Min, f32Sub, f32Result;
void main(void)
{
f32Min = FRAC32(-0.5);
f32Sub = FRAC32(0.8);
}
/* f32Min = -0.5 */
/* f32Sub = 0.8 */
/* f32Result = sat(f32Min - f32Sub) */
f32Result = MLIB_SubSat_F32(f32Min,f32Sub);
2.57 MLIB_Sub4
The MLIB_Sub4 functions return the subtraction of three subtrahends from the minuend.
The function does not saturate the output. See the following equation:
Equation 54. Algorithm formula
2.57.1 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.
• Floating-point output - the output is a floating-point number; the result is within the
full range.
The available versions of the MLIB_Sub4 function are shown in the following table.
Table 2-57. Function versions
Function name
Input type
Minuend
Sub. 1
Sub. 2
Sub. 3
Result
type
Description
MLIB_Sub4_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Subtraction of three 16-bit fractional
subtrahends from 16-bit fractional
minuend. The output is within the range
<-1 ; 1).
MLIB_Sub4_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Subtraction of three 32-bit fractional
subtrahends from 32-bit fractional
minuend. The output is within the range
<-1 ; 1).
MLIB_Sub4_FLT
float_t
float_t
float_t
float_t
float_t
Subtraction of three 32-bit single precision
floating-point subtrahends from 32-bit
single precision floating-point. The output
is within the full range.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
109
MLIB_Sub4Sat
2.57.2 Declaration
The available MLIB_Sub4 functions have the following declarations:
frac16_t MLIB_Sub4_F16(frac16_t f16Min, frac16_t f16Sub1, frac16_t f16Sub2, frac16_t f16Sub3)
frac32_t MLIB_Sub4_F32(frac32_t f32Min, frac32_t f32Sub1, frac32_t f32Sub2, frac32_t f32Sub3)
float_t MLIB_Sub4_FLT(float_t fltMin, float_t fltSub1, float_t fltSub2, float_t fltSub3)
2.57.3 Function use
The use of the MLIB_Sub4 function is shown in the following example:
#include "mlib.h"
static frac16_t f16Result, f16Min, f16Sub1, f16Sub2, f16Sub3;
void main(void)
{
f16Min = FRAC16(0.2);
f16Sub1 = FRAC16(0.3);
f16Sub2 = FRAC16(-0.5);
f16Sub3 = FRAC16(0.2);
/*
/*
/*
/*
f16Min = 0.2 */
f16Sub1 = 0.3 */
f16Sub2 = -0.5 */
f16Sub3 = 0.2 */
/* f16Result = sat(f16Min - f16Sub1 - f16Sub2 - f16Sub3) */
f16Result = MLIB_Sub4_F16(f16Min, f16Sub1, f16Sub2, f16Sub3);
}
2.58 MLIB_Sub4Sat
The MLIB_Sub4Sat functions return the subtraction of three subtrahends from the
minuend. The function saturates the output. See the following equation:
Equation 55. Algorithm formula
2.58.1 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.
MLIB User's Guide, Rev. 0, 10/2015
110
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the MLIB_Sub4Sat function are shown in the following table.
Table 2-58. Function versions
Function name
Input type
Minuend
Sub. 1
Sub. 2
Sub. 3
Result
type
Description
MLIB_Sub4Sat_F16
frac16_t
frac16_t
frac16_t
frac16_t
frac16_t
Subtraction of three 16-bit fractional
subtrahends from 16-bit fractional
minuend. The output is within the range
<-1 ; 1).
MLIB_Sub4Sat_F32
frac32_t
frac32_t
frac32_t
frac32_t
frac32_t
Subtraction of three 32-bit fractional
subtrahends from 32-bit fractional
minuend. The output is within the range
<-1 ; 1).
2.58.2 Declaration
The available MLIB_Sub4Sat functions have the following declarations:
frac16_t MLIB_Sub4Sat_F16(frac16_t f16Min, frac16_t f16Sub1, frac16_t f16Sub2, frac16_t
f16Sub3)
frac32_t MLIB_Sub4Sat_F32(frac32_t f32Min, frac32_t f32Sub1, frac32_t f32Sub2, frac32_t
f32Sub3)
2.58.3 Function use
The use of the MLIB_Sub4Sat function is shown in the following example:
#include "mlib.h"
static frac32_t f32Result, f32Min, f32Sub1, f32Sub2, f32Sub3;
void main(void)
{
f32Min = FRAC32(0.2);
f32Sub1 = FRAC32(0.8);
f32Sub2 = FRAC32(-0.1);
f32Sub3 = FRAC32(0.7);
}
/*
/*
/*
/*
f32Min = 0.2 */
f32Sub1 = 0.8 */
f32Sub2 = -0.1 */
f32Sub3 = 0.7 */
/* f32Result = sat(f32Min - f32Sub1 - f32Sub2 - f32Sub3) */
f32Result = MLIB_Sub4Sat_F32(f32Min, f32Sub1, f32Sub2, f32Sub3);
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
111
MLIB_Sub4Sat
MLIB User's Guide, Rev. 0, 10/2015
112
Freescale Semiconductor, Inc.
Appendix A
Library types
A.1 bool_t
The bool_t type is a logical 16-bit type. It is able to store the boolean variables with two
states: TRUE (1) or FALSE (0). Its definition is as follows:
typedef unsigned short bool_t;
The following figure shows the way in which the data is stored by this type:
Table A-1. Data storage
15
14
13
12
11
10
9
Value
TRUE
FALSE
8
7
6
5
4
3
2
1
Logi
cal
Unused
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
1
0
0
1
0
0
0
0
0
0
To store a logical value as bool_t, use the FALSE or TRUE macros.
A.2 uint8_t
The uint8_t type is an unsigned 8-bit integer type. It is able to store the variables within
the range <0 ; 255>. Its definition is as follows:
typedef unsigned char int8_t;
The following figure shows the way in which the data is stored by this type:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
113
uint16_t
Table A-2. Data storage
7
6
5
4
Value
2
1
0
1
1
1
1
1
1
0
0
1
1
Integer
1
255
3
1
1
1
F
0
11
F
0
0
0
1
0
0
0
124
B
1
1
1
1
1
7
1
159
C
0
0
1
1
1
9
F
A.3 uint16_t
The uint16_t type is an unsigned 16-bit integer type. It is able to store the variables
within the range <0 ; 65535>. Its definition is as follows:
typedef unsigned short uint16_t;
The following figure shows the way in which the data is stored by this type:
Table A-3. Data storage
15
14
13
12
11
10
9
8
Value
65535
5
15518
40768
7
6
5
4
3
2
1
0
1
1
1
1
1
1
0
0
0
1
0
1
1
0
0
0
Integer
1
1
0
0
1
1
1
1
0
0
0
0
F
0
1
0
1
0
0
0
0
F
1
1
1
1
1
0
1
0
1
0
5
0
1
1
1
9
1
F
F
0
C
0
9
1
0
3
1
1
F
0
0
1
1
0
1
E
0
4
0
0
0
0
A.4 uint32_t
MLIB User's Guide, Rev. 0, 10/2015
114
Freescale Semiconductor, Inc.
Appendix A Library types
The uint32_t type is an unsigned 32-bit integer type. It is able to store the variables
within the range <0 ; 4294967295>. Its definition is as follows:
typedef unsigned long uint32_t;
The following figure shows the way in which the data is stored by this type:
Table A-4. Data storage
31
24 23
16 15
Value
8 7
0
Integer
4294967295
F
F
F
F
F
F
F
F
2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
3451051828
C
D
B
2
D
F
3
4
A.5 int8_t
The int8_t type is a signed 8-bit integer type. It is able to store the variables within the
range <-128 ; 127>. Its definition is as follows:
typedef char int8_t;
The following figure shows the way in which the data is stored by this type:
Table A-5. Data storage
7
Value
127
-128
60
-97
6
5
4
Sign
0
3
2
1
1
1
1
1
0
0
0
0
0
1
0
0
0
0
0
1
1
0
1
1
1
1
3
1
1
F
8
0
0
Integer
7
1
1
0
C
0
1
1
9
1
F
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
115
int16_t
A.6 int16_t
The int16_t type is a signed 16-bit integer type. It is able to store the variables within the
range <-32768 ; 32767>. Its definition is as follows:
typedef short int16_t;
The following figure shows the way in which the data is stored by this type:
Table A-6. Data storage
15
Value
32767
-32768
15518
-24768
14
13
12
11
10
9
8
Sign
7
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
1
0
0
0
Integer
0
1
1
1
1
1
7
1
0
0
0
0
0
0
1
0
1
F
0
0
0
0
0
1
1
1
3
1
1
F
8
0
1
0
1
1
0
1
0
0
0
0
0
0
1
0
C
9
F
0
0
1
1
1
9
1
1
0
1
F
E
0
0
0
0
4
0
A.7 int32_t
The int32_t type is a signed 32-bit integer type. It is able to store the variables within the
range <-2147483648 ; 2147483647>. Its definition is as follows:
typedef long int32_t;
The following figure shows the way in which the data is stored by this type:
Table A-7. Data storage
31
Value
24 23
16 15
S
8 7
0
Integer
2147483647
7
F
F
F
F
F
F
F
-2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
-843915468
C
D
B
2
D
F
3
4
MLIB User's Guide, Rev. 0, 10/2015
116
Freescale Semiconductor, Inc.
Appendix A Library types
A.8 frac8_t
The frac8_t type is a signed 8-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef char frac8_t;
The following figure shows the way in which the data is stored by this type:
Table A-8. Data storage
7
Value
0.99219
-1.0
0.46875
-0.75781
6
5
4
3
Sign
2
1
0
1
1
1
0
0
0
0
1
1
Fractional
0
1
1
1
1
7
1
0
F
0
0
0
0
8
0
0
0
1
1
1
1
3
1
0
C
0
1
1
1
9
F
To store a real number as frac8_t, use the FRAC8 macro.
A.9 frac16_t
The frac16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef short frac16_t;
The following figure shows the way in which the data is stored by this type:
Table A-9. Data storage
15
Value
0.99997
-1.0
14
13
12
11
10
9
8
Sign
0
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
Fractional
1
1
1
1
1
7
1
7
0
1
1
1
F
0
0
0
0
F
0
0
0
0
F
0
0
0
0
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
117
frac32_t
Table A-9. Data storage (continued)
8
0.47357
-0.75586
0
0
0
1
1
1
1
3
1
0
0
0
0
1
0
C
0
1
1
1
9
0
0
1
1
1
9
1
1
0
1
F
1
0
0
0
E
0
0
0
0
4
0
To store a real number as frac16_t, use the FRAC16 macro.
A.10 frac32_t
The frac32_t type is a signed 32-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef long frac32_t;
The following figure shows the way in which the data is stored by this type:
Table A-10. Data storage
31
Value
24 23
16 15
S
8 7
0
Fractional
0.9999999995
7
F
F
F
F
F
F
F
-1.0
8
0
0
0
0
0
0
0
0.02606645970
0
3
5
6
2
5
5
0
-0.3929787632
C
D
B
2
D
F
3
4
To store a real number as frac32_t, use the FRAC32 macro.
A.11 acc16_t
The acc16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-256 ; 256). Its definition is as follows:
typedef short acc16_t;
The following figure shows the way in which the data is stored by this type:
MLIB User's Guide, Rev. 0, 10/2015
118
Freescale Semiconductor, Inc.
Appendix A Library types
Table A-11. Data storage
15
Value
255.9921875
-256.0
1.0
-1.0
13.7890625
-89.71875
14
13
12
Sign
11
10
9
8
7
6
5
4
Integer
0
1
1
1
1
1
0
0
0
0
8
0
0
0
1
0
0
0
1
1
1
1
0
0
0
0
0
1
0
1
D
1
1
1
0
0
0
0
0
0
0
0
0
1
0
0
0
1
0
0
0
0
0
0
1
0
0
0
0
0
0
8
1
0
1
8
1
1
1
0
0
1
1
6
0
0
F
0
F
0
1
0
0
1
0
1
1
0
1
1
F
0
0
F
0
1
0
0
1
1
F
0
2
Fractional
1
7
3
0
1
0
0
1
E
1
1
0
0
3
5
1
0
0
1
2
4
To store a real number as acc16_t, use the ACC16 macro.
A.12 acc32_t
The acc32_t type is a signed 32-bit accumulator type. It is able to store the variables
within the range <-65536 ; 65536). Its definition is as follows:
typedef long acc32_t;
The following figure shows the way in which the data is stored by this type:
Table A-12. Data storage
31
Value
24 23
S
16 15
8 7
Integer
0
Fractional
65535.999969
7
F
F
F
F
F
F
F
-65536.0
8
0
0
0
0
0
0
0
1.0
0
0
0
0
8
0
0
0
-1.0
F
F
F
F
8
0
0
0
23.789734
0
0
0
B
E
5
1
6
-1171.306793
F
D
B
6
5
8
B
C
To store a real number as acc32_t, use the ACC32 macro.
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
119
float_t
A.13 float_t
The float_t type is a signed 32-bit single precision floating-point type, defined by IEEE
754. It is able to store the full precision (normalized) finite variables within the range
<-3.40282 · 1038 ; 3.40282 · 1038) with the minimum resolution of 2-23. The smallest
normalized number is ±1.17549 · 10-38. Nevertheless, the denormalized numbers (with
reduced precision) reach yet lower values, from ±1.40130 · 10-45 to ±1.17549 · 10-38. The
standard also defines the additional values:
•
•
•
•
Negative zero
Infinity
Negative infinity
Not a number
The 32-bit type is composed of:
• Sign (bit 31)
• Exponent (bits 23 to 30)
• Mantissa (bits 0 to 22)
The conversion of the number is straighforward. The sign of the number is stored in bit
31. The binary exponent is decoded as an integer from bits 23 to 30 by subtracting 127.
The mantissa (fraction) is stored in bits 0 to 22. An invisible leading bit (it is not actually
stored) with value 1.0 is placed in front; therefore, bit 23 has a value of 0.5, bit 22 has a
value 0.25, and so on. As a result, the mantissa has a value between 1.0 and 2. If the
exponent reaches -127 (binary 00000000), the leading 1.0 is no longer used to enable the
gradual underflow.
The float_t type definition is as follows:
typedef float float_t;
The following figure shows the way in which the data is stored by this type:
Table A-13. Data storage - normalized values
31
Value
(2.0 - 2-23) · 2127
≈ 3.40282 ·
24 23
S
1038
16 15
8 7
Exponent
0
Mantissa
0 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
7
F
7
F
F
F
F
F
-(2.0 - 2-23) · 2127 1 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
≈ -3.40282 · 1038
F
F
7
F
F
F
F
F
Table continues on the next page...
MLIB User's Guide, Rev. 0, 10/2015
120
Freescale Semiconductor, Inc.
Appendix A Library types
Table A-13. Data storage - normalized values (continued)
2-126
0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
≈ 1.17549 · 10-38
-2-126
≈ -1.17549 ·
0
0
8
0
0
0
0
0
1 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
10-38
1.0
8
0
8
0
0
0
0
0
0 0 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
3
-1.0
F
8
0
0
0
0
0
1 0 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
B
π
F
8
0
0
0
0
0
0 1 0 0 0 0 0 0 0 1 0 0 1 0 0 1 0 0 0 0 1 1 1 1 1 1 0 1 1 0 1 1
≈ 3.1415927
-20810.086
4
0
4
9
0
F
D
B
1 1 0 0 0 1 1 0 1 0 1 0 0 0 1 0 1 0 0 1 0 1 0 0 0 0 1 0 1 1 0 0
C
6
A
2
9
4
2
C
Table A-14. Data storage - denormalized values
31
Value
24 23
S
0.0
16 15
8 7
Exponent
0
Mantissa
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0
-0.0
0
0
0
0
0
0
0
1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
8
0
0
0
0
0
0
0
(1.0 - 2-23) · 2-126 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
≈ 1.17549 · 10-38
0
0
7
F
F
F
F
F
-(1.0 - 2-23) · 2-126 1 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
≈ -1.17549 · 10-38
2-1 · 2-126
≈ 5.87747 · 10-39
-2-1 · 2-126
≈ -5.87747 ·
10-39
2-23 · 2-126
≈ 1.40130 ·
10-45
-2-23 · 2-126
≈ -1.40130 ·
10-45
8
0
7
F
F
F
F
F
0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0
0
4
0
0
0
0
0
1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
8
0
4
0
0
0
0
0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1
0
0
0
0
0
0
0
1
1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1
8
0
0
0
0
0
0
1
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
121
FALSE
Table A-15. Data storage - special values
31
Value
24 23
S
∞
0
Mantissa
0 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
F
8
0
0
0
0
0
1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
F
Not a number
8 7
Exponent
7
-∞
16 15
F
8
0
* 1 1 1 1 1 1 1 1
7/F
F
0
0
0
0
non zero
800001 to FFFFFF
A.14 FALSE
The FALSE macro serves to write a correct value standing for the logical FALSE value
of the bool_t type. Its definition is as follows:
#define FALSE
((bool_t)0)
#include "mlib.h"
static bool_t bVal;
void main(void)
{
bVal = FALSE;
}
/* bVal = FALSE */
A.15 TRUE
The TRUE macro serves to write a correct value standing for the logical TRUE value of
the bool_t type. Its definition is as follows:
#define TRUE
((bool_t)1)
#include "mlib.h"
static bool_t bVal;
void main(void)
{
bVal = TRUE;
}
/* bVal = TRUE */
MLIB User's Guide, Rev. 0, 10/2015
122
Freescale Semiconductor, Inc.
Appendix A Library types
A.16 FRAC8
The FRAC8 macro serves to convert a real number to the frac8_t type. Its definition is as
follows:
#define FRAC8(x) ((frac8_t)((x) < 0.9921875 ? ((x) >= -1 ? (x)*0x80 : 0x80) : 0x7F))
The input is multiplied by 128 (=27). The output is limited to the range <0x80 ; 0x7F>,
which corresponds to <-1.0 ; 1.0-2-7>.
#include "mlib.h"
static frac8_t f8Val;
void main(void)
{
f8Val = FRAC8(0.187);
}
/* f8Val = 0.187 */
A.17 FRAC16
The FRAC16 macro serves to convert a real number to the frac16_t type. Its definition is
as follows:
#define FRAC16(x) ((frac16_t)((x) < 0.999969482421875 ? ((x) >= -1 ? (x)*0x8000 : 0x8000) :
0x7FFF))
The input is multiplied by 32768 (=215). The output is limited to the range <0x8000 ;
0x7FFF>, which corresponds to <-1.0 ; 1.0-2-15>.
#include "mlib.h"
static frac16_t f16Val;
void main(void)
{
f16Val = FRAC16(0.736);
}
/* f16Val = 0.736 */
A.18 FRAC32
The FRAC32 macro serves to convert a real number to the frac32_t type. Its definition is
as follows:
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
123
ACC16
#define FRAC32(x) ((frac32_t)((x) < 1 ? ((x) >= -1 ? (x)*0x80000000 : 0x80000000) :
0x7FFFFFFF))
The input is multiplied by 2147483648 (=231). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-1.0 ; 1.0-2-31>.
#include "mlib.h"
static frac32_t f32Val;
void main(void)
{
f32Val = FRAC32(-0.1735667);
}
/* f32Val = -0.1735667 */
A.19 ACC16
The ACC16 macro serves to convert a real number to the acc16_t type. Its definition is as
follows:
#define ACC16(x) ((acc16_t)((x) < 255.9921875 ? ((x) >= -256 ? (x)*0x80 : 0x8000) : 0x7FFF))
The input is multiplied by 128 (=27). The output is limited to the range <0x8000 ;
0x7FFF> that corresponds to <-256.0 ; 255.9921875>.
#include "mlib.h"
static acc16_t a16Val;
void main(void)
{
a16Val = ACC16(19.45627);
}
/* a16Val = 19.45627 */
A.20 ACC32
The ACC32 macro serves to convert a real number to the acc32_t type. Its definition is as
follows:
#define ACC32(x) ((acc32_t)((x) < 65535.999969482421875 ? ((x) >= -65536 ? (x)*0x8000 :
0x80000000) : 0x7FFFFFFF))
The input is multiplied by 32768 (=215). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-65536.0 ; 65536.0-2-15>.
MLIB User's Guide, Rev. 0, 10/2015
124
Freescale Semiconductor, Inc.
#include "mlib.h"
static acc32_t a32Val;
void main(void)
{
a32Val = ACC32(-13.654437);
}
/* a32Val = -13.654437 */
MLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
125
MLIB User's Guide, Rev. 0, 10/2015
126
Freescale Semiconductor, Inc.
How to Reach Us:
Home Page:
freescale.com
Web Support:
freescale.com/support
Information in this document is provided solely to enable system and
software implementers to use Freescale products. There are no express
or implied copyright licenses granted hereunder to design or fabricate
any integrated circuits based on the information in this document.
Freescale reserves the right to make changes without further notice to
any products herein.
Freescale makes no warranty, representation, or guarantee regarding
the suitability of its products for any particular purpose, nor does
Freescale assume any liability arising out of the application or use of
any product or circuit, and specifically disclaims any and all liability,
including without limitation consequential or incidental damages.
“Typical” parameters that may be provided in Freescale data sheets
and/or specifications can and do vary in different applications, and
actual performance may vary over time. All operating parameters,
including “typicals,” must be validated for each customer application by
customer's technical experts. Freescale does not convey any license
under its patent rights nor the rights of others. Freescale sells products
pursuant to standard terms and conditions of sale, which can be found
at the following address: www.freescale.com/salestermsandconditions.
Freescale and the Freescale logo are trademarks of Freescale
Semiconductor, Inc. ARM and Cortex are the registered trademarks of
ARM Limited, in EU and/or elsewhere. ARM logo is the trademark of
ARM Limited. All rights reserved. All other product or service names are
the property of their respective owners.
© 2015 Freescale Semiconductor, Inc.
Document Number CM7FMLIBUG
Revision 0, 10/2015