NXP MLIB User Manual

MLIB User's Guide
ARM® Cortex® M4
Document Number: CM4MLIBUG
Rev. 5, 12/2020
MLIB User's Guide, Rev. 5, 12/2020
2 NXP Semiconductors
Contents
Section number Title Page
Library
1.1 Introduction.................................................................................................................................................................... 7
1.2 Library integration into project (MCUXpresso IDE) ....................................................................................................9
1.3 Library integration into project (Kinetis Design Studio) .............................................................................................. 19
1.4 Library integration into project (Keil µVision) ............................................................................................................. 25
1.5 Library integration into project (IAR Embedded Workbench) ..................................................................................... 35
Algorithms in detail
2.1 MLIB_Abs......................................................................................................................................................................45
2.2 MLIB_AbsSat.................................................................................................................................................................46
2.3 MLIB_Add..................................................................................................................................................................... 47
2.4 MLIB_AddSat................................................................................................................................................................ 49
2.5 MLIB_Add4................................................................................................................................................................... 50
2.6 MLIB_Add4Sat.............................................................................................................................................................. 51
2.7 MLIB_Clb...................................................................................................................................................................... 53
2.8 MLIB_Conv................................................................................................................................................................... 54
2.9 MLIB_Div...................................................................................................................................................................... 55
2.10 MLIB_DivSat.................................................................................................................................................................57
2.11 MLIB_Div1Q................................................................................................................................................................. 58
2.12 MLIB_Div1QSat............................................................................................................................................................ 60
2.13 MLIB_Log2....................................................................................................................................................................62
2.14 MLIB_Mac.....................................................................................................................................................................63
2.15 MLIB_MacSat................................................................................................................................................................64
2.16 MLIB_MacRnd.............................................................................................................................................................. 66
2.17 MLIB_MacRndSat......................................................................................................................................................... 68
2.18 MLIB_Mac4...................................................................................................................................................................69
2.19 MLIB_Mac4Sat..............................................................................................................................................................71
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 3
Section number Title Page
2.20 MLIB_Mac4Rnd............................................................................................................................................................ 72
2.21 MLIB_Mac4RndSat....................................................................................................................................................... 74
2.22 MLIB_Mnac...................................................................................................................................................................75
2.23 MLIB_MnacSat..............................................................................................................................................................77
2.24 MLIB_MnacRnd............................................................................................................................................................ 78
2.25 MLIB_MnacRndSat....................................................................................................................................................... 80
2.26 MLIB_Msu.....................................................................................................................................................................81
2.27 MLIB_MsuSat................................................................................................................................................................83
2.28 MLIB_MsuRnd.............................................................................................................................................................. 84
2.29 MLIB_MsuRndSat......................................................................................................................................................... 86
2.30 MLIB_Msu4...................................................................................................................................................................87
2.31 MLIB_Msu4Sat..............................................................................................................................................................89
2.32 MLIB_Msu4Rnd............................................................................................................................................................ 90
2.33 MLIB_Msu4RndSat....................................................................................................................................................... 92
2.34 MLIB_Mul..................................................................................................................................................................... 93
2.35 MLIB_MulSat................................................................................................................................................................ 95
2.36 MLIB_MulNeg...............................................................................................................................................................96
2.37 MLIB_MulNegSat..........................................................................................................................................................98
2.38 MLIB_MulRnd...............................................................................................................................................................99
2.39 MLIB_MulRndSat..........................................................................................................................................................101
2.40 MLIB_MulNegRnd........................................................................................................................................................ 103
2.41 MLIB_MulNegRndSat...................................................................................................................................................105
2.42 MLIB_Neg..................................................................................................................................................................... 106
2.43 MLIB_NegSat................................................................................................................................................................ 107
2.44 MLIB_Rcp......................................................................................................................................................................108
2.45 MLIB_Rcp1Q.................................................................................................................................................................110
2.46 MLIB_Rnd..................................................................................................................................................................... 111
2.47 MLIB_RndSat................................................................................................................................................................ 112
2.48 MLIB_Sat.......................................................................................................................................................................113
MLIB User's Guide, Rev. 5, 12/2020
4 NXP Semiconductors
Section number Title Page
2.49 MLIB_Sh1L................................................................................................................................................................... 114
2.50 MLIB_Sh1LSat.............................................................................................................................................................. 115
2.51 MLIB_Sh1R................................................................................................................................................................... 117
2.52 MLIB_ShL..................................................................................................................................................................... 118
2.53 MLIB_ShLSat................................................................................................................................................................ 119
2.54 MLIB_ShR..................................................................................................................................................................... 120
2.55 MLIB_ShLBi..................................................................................................................................................................122
2.56 MLIB_ShLBiSat.............................................................................................................................................................123
2.57 MLIB_ShRBi................................................................................................................................................................. 124
2.58 MLIB_ShRBiSat............................................................................................................................................................ 126
2.59 MLIB_Sign.....................................................................................................................................................................127
2.60 MLIB_Sub......................................................................................................................................................................128
2.61 MLIB_SubSat.................................................................................................................................................................130
2.62 MLIB_Sub4....................................................................................................................................................................131
2.63 MLIB_Sub4Sat...............................................................................................................................................................133
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 5
MLIB User's Guide, Rev. 5, 12/2020
6 NXP Semiconductors
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 M4ARM Cortex M33ARM Cortex M33F core-based microcontrollers. This library contains optimized functions.
1.1.2

Data types

MLIB supports several data types: (un)signed integer, fractional, and accumulator. The integer data types are useful for general-purpose computation; they are familiar to the MPU and MCU programmers. The fractional data types enable powerful numeric and digital-signal-processing algorithms to be implemented. The accumulator data type is a combination of both; that means it has the integer and fractional portions.
The following list shows the integer types defined in the libraries:
Unsigned 16-bit integer —<0 ; 65535> with the minimum resolution of 1
Signed 16-bit integer —<-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
The following list shows the fractional types defined in the libraries:
Fixed-point 16-bit fractional —<-1 ; 1 - 2
Fixed-point 32-bit fractional —<-1 ; 1 - 2
-15
> with the minimum resolution of 2
-31
> with the minimum resolution of 2
-15
-31
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 7
Introduction
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
Fixed-point 32-bit accumulator —<-65536.0 ; 65536.0 - 2 resolution of 2
-7
-15
-15
> with the minimum

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

1.1.4 Supported compilers

MLIB for the ARM Cortex M4ARM Cortex M33ARM Cortex M33F core is written in C language or assembly language with C-callable interface depending on the specific function. The library is built and tested using the following compilers:
• MCUXpresso IDE
• IAR Embedded Workbench
• Keil µVision
MLIB User's Guide, Rev. 5, 12/2020
8 NXP Semiconductors
Chapter 1 Library
For the MCUXpresso IDE, the library is delivered in the mlib.a file. For the Kinetis Design Studio, the library is delivered in the mlib.a file. 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
MLIB for the ARM Cortex M4ARM Cortex M33ARM Cortex M33F core is written in C language or assembly language with C-callable interface depending on the specific function. Some functions from this library are inline type, which are compiled together with project using this library. The optimization level for inline function is usually defined by the specific compiler setting. It can cause an issue especially when high optimization level is set. Therefore the optimization level for all inline assembly written functions is defined by compiler pragmas using macros. The configuration header file RTCESL_cfg.h is located in: specific library folder\MLIB\Include. The optimization level can be changed by modifying the macro value for specific compiler. In case of any change the library functionality is not guaranteed.
Similarly as optimization level the PowerQuad DSP Coprocessor and Accelerator support can be disable or enable if it has not been done by defined symbol RTCESL_PQ_ON or RTCESL_PQ_OFF in project setting described in the PowerQuad DSP Coprocessor and Accelerator support cheaper for specific compiler.

Library configuration

1.1.6
1. The equations describing the algorithms are symbolic. If there is positive 1, the
2. The library functions that round the result (the API contains Rnd) round to nearest
1.2
NXP Semiconductors 9

Special issues

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.
(half up).

Library integration into project (MCUXpresso IDE)

MLIB User's Guide, Rev. 5, 12/2020
Library integration into project (MCUXpresso IDE)
This section provides a step-by-step guide on how to quickly and easily include MLIB into any MCUXpresso SDK example or demo application projects using MCUXpresso IDE. This example uses the default installation path (C:\NXP\RTCESL \CM4CM33CM33F_RTCESL_4.6_MCUX). If you have a different installation path, use that path instead.

1.2.1 PowerQuad DSP Coprocessor and Accelerator support

Some LPC platforms (LPC55S6x) contain a hardware accelerator dedicated to common calculations in DSP applications. This section shows how to turn the PowerQuad (PQ) support for a function on and off.
1. In the MCUXpresso SDK project name node or in the left-hand part, click Properties or select Project > Properties from the menu. A project properties dialog appears.
2. Expand the C/C++ Build node and select Settings. See .
3. On the right-hand side, under the MCU C Compiler node, click the Preprocessor node. See .
Figure 1-1. Defined symbols
4. In the right-hand part of the dialog, click the Add... icon located next to the Defined symbols (-D) title.
MLIB User's Guide, Rev. 5, 12/2020
10 NXP Semiconductors
5. In the dialog that appears (see ), type the following:
• RTCESL_PQ_ON—to turn the PowerQuad support on
• RTCESL_PQ_OFF—to turn the PowerQuad support off If neither of these two defines is defined, the hardware division and square root support is turned off by default.
Figure 1-2. Symbol definition
6. Click OK in the dialog.
7. Click OK in the main dialog.
8. Ensure the PowerQuad moduel to be clocked by calling function RTCESL_PQ_Init(); prior to the first function using PQ module calling.
Chapter 1 Library
See the device reference manual to verify whether the device contains the PowerQuad DSP Coprocessor and Accelerator support.
1.2.2

Library path variable

To make the library integration easier, create a variable that holds the information about the library path.
1. Right-click the MCUXpresso SDK project name node in the left-hand part and click Properties, or select Project > Properties from the menu. A project properties dialog appears.
2. Expand the Resource node and click Linked Resources. See Figure 1-3.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 11
Library integration into project (MCUXpresso IDE)
Figure 1-3. Project properties
3. Click the New… button in the right-hand side.
4. In the dialog that appears (see Figure 1-4), type this variable name into the Name box: RTCESL_LOC.
5. Select the library parent folder by clicking Folder…, or just type the following path into the Location box: C:\NXP\RTCESL\CM4CM33CM33F_RTCESL_4.6_MCUX. Click OK.
MLIB User's Guide, Rev. 5, 12/2020
12 NXP Semiconductors
Chapter 1 Library
Figure 1-4. New variable
6. Create such variable for the environment. Expand the C/C++ Build node and click Environment.
7. Click the Add… button in the right-hand side.
8. In the dialog that appears (see Figure 1-5), type this variable name into the Name box: RTCESL_LOC.
9. Type the library parent folder path into the Value box: C:\NXP\RTCESL \CM4CM33CM33F_RTCESL_4.6_MCUX.
10. Tick the Add to all configurations box to use this variable in all configurations. See
Figure 1-5.
11. Click OK.
12. In the previous dialog, click OK.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 13
Library integration into project (MCUXpresso IDE)
MLIB User's Guide, Rev. 5, 12/2020
14 NXP Semiconductors
Chapter 1 Library
Figure 1-5. Environment variable
1.2.3

Library folder addition

To use the library, add it into the Project tree dialog.
1. Right-click the MCUXpresso SDK project name node in the left-hand part and click New > Folder, or select File > New > Folder from the menu. A dialog appears.
2. Click Advanced to show the advanced options.
3. To link the library source, select the Link to alternate location (Linked Folder) option.
4. Click Variables..., select the RTCESL_LOC variable in the dialog, click OK, and/or type the variable name into the box. See Figure 1-6.
5. Click Finish, and the library folder is linked in the project. See Figure 1-7.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 15
Library integration into project (MCUXpresso IDE)
Figure 1-6. Folder link
Figure 1-7. Projects libraries paths
1.2.4

Library path setup

1. Right-click the MCUXpresso SDK project name node in the left-hand part and click Properties, or select Project > Properties from the menu. The project properties dialog appears.
2. Expand the C/C++ General node, and click Paths and Symbols.
3. In the right-hand dialog, select the Library Paths tab. See Figure 1-9.
4. Click the Add… button on the right, and a dialog appears.
5. Look for the RTCESL_LOC variable by clicking Variables…, and then finish the path in the box by adding the following (see Figure 1-8): ${RTCESL_LOC}\MLIB.
6. Click OK, you will see the path added into the list. See Figure 1-9.
MLIB User's Guide, Rev. 5, 12/2020
16 NXP Semiconductors
Figure 1-8. Library path inclusion
Chapter 1 Library
Figure 1-9. Library paths
7. After adding the library path, add the library file. Click the Libraries tab. See Figure
1-11.
8. Click the Add… button on the right, and a dialog appears.
9. Type the following into the File text box (see Figure 1-10): :mlib.a
10. Click OK, and you will see the library added in the list. See Figure 1-11.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 17
Library integration into project (MCUXpresso IDE)
Figure 1-10. Library file inclusion
Figure 1-11. Libraries
11. In the right-hand dialog, select the Includes tab, and click GNU C in the Languages list. See Figure 1-13.
12. Click the Add… button on the right, and a dialog appears. See Figure 1-12.
13. Look for the RTCESL_LOC variable by clicking Variables…, and then finish the path in the box to be: ${RTCESL_LOC}\MLIB\Include
14. Click OK, and you will see the path added in the list. See Figure 1-13. Click OK.
Figure 1-12. Library include path addition
MLIB User's Guide, Rev. 5, 12/2020
18 NXP Semiconductors
Chapter 1 Library
Figure 1-13. Compiler setting
Type the #include syntax into the code where you want to call the library functions. In the left-hand dialog, open the required .c file. After the file opens, include the following line into the #include section:
#include "mlib_FP.h"
When you click the Build icon (hammer), the project is compiled without errors.
1.3

Library integration into project (Kinetis Design Studio)

This section provides a step-by-step guide on how to quickly and easily include MLIB into an empty project or any MCUXpresso SDK example or demo application projects using Kinetis Design Studio. This example uses the default installation path (C:\NXP \RTCESL\CM4CM33CM33F_RTCESL_4.6_KDS). If you have a different installation path, use that path instead. If you want to use an existing MCUXpresso SDK project (for example the hello_world project) see Library path variable. If not, continue with the next section.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 19
Library integration into project (Kinetis Design Studio)

1.3.1 Library path variable

To make the library integration easier, create a variable that will hold the information about the library path.
1. Right-click the MyProject01 or MCUXpresso SDK project name node in the left­hand part and click Properties, or select Project > Properties from the menu. A project properties dialog appears.
2. Expand the Resource node and click Linked Resources. See Figure 1-14.
Figure 1-14. Project properties
3. Click the New… button in the right-hand side.
4. In the dialog that appears (see Figure 1-15), type this variable name into the Name box: RTCESL_LOC.
5. Select the library parent folder by clicking Folder…, or just type the following path into the Location box: C:\NXP\RTCESL\CM4CM33CM33F_RTCESL_4.6_KDS. Click OK.
MLIB User's Guide, Rev. 5, 12/2020
20 NXP Semiconductors
Chapter 1 Library
Figure 1-15. New variable
6. Create such variable for the environment. Expand the C/C++ Build node and click Environment.
7. Click the Add… button in the right-hand side.
8. In the dialog that appears (see Figure 1-16), type this variable name into the Name box: RTCESL_LOC.
9. Type the library parent folder path into the Value box: C:\NXP\RTCESL \CM4CM33CM33F_RTCESL_4.6_KDS.
10. Tick the Add to all configurations box to use this variable in all configurations. See
Figure 1-16.
11. Click OK.
12. In the previous dialog, click OK.
Figure 1-16. Environment variable
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 21
Library integration into project (Kinetis Design Studio)

1.3.2 Library folder addition

To use the library, add it into the Project tree dialog.
1. Right-click the MyProject01 or MCUXpresso SDK project name node in the left­hand part and click New > Folder, or select File > New > Folder from the menu. A dialog appears.
2. Click Advanced to show the advanced options.
3. To link the library source, select the option Link to alternate location (Linked Folder).
4. Click Variables..., select the RTCESL_LOC variable in the dialog, click OK, and/or type the variable name into the box. See Figure 1-17.
5. Click Finish, and you will see the library folder linked in the project. See Figure
1-18.
Figure 1-17. Folder link
MLIB User's Guide, Rev. 5, 12/2020
22 NXP Semiconductors
Chapter 1 Library
Figure 1-18. Projects libraries paths

1.3.3 Library path setup

1. Right-click the MyProject01 or MCUXpresso SDK project name node in the left­hand part and click Properties, or select Project > Properties from the menu. A project properties dialog appears.
2. Expand the C/C++ General node, and click Paths and Symbols.
3. In the right-hand dialog, select the Library Paths tab. See Figure 1-20.
4. Click the Add… button on the right, and a dialog appears.
5. Look for the RTCESL_LOC variable by clicking Variables…, and then finish the path in the box by adding the following (see Figure 1-19): ${RTCESL_LOC}\MLIB.
6. Click OK, and the path will be visible in the list. See Figure 1-20.
Figure 1-19. Library path inclusion
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 23
Library integration into project (Kinetis Design Studio)
Figure 1-20. Library paths
7. After adding the library path, add the library file. Click the Libraries tab. See Figure
1-22.
8. Click the Add… button on the right, and a dialog appears.
9. Type the following into the File text box (see Figure 1-21): :mlib.a
10. Click OK, and you will see the library added in the list. See Figure 1-22.
Figure 1-21. Library file inclusion
Figure 1-22. Libraries
11. In the right-hand dialog, select the Includes tab, and click GNU C in the Languages list. See Figure 1-24.
12. Click the Add… button on the right, and a dialog appears. See Figure 1-23.
13. Look for the RTCESL_LOC variable by clicking Variables…, and then finish the path in the box to be: ${RTCESL_LOC}\MLIB\Include
14. Click OK, and you will see the path added in the list. See Figure 1-24. Click OK.
MLIB User's Guide, Rev. 5, 12/2020
24 NXP Semiconductors
Figure 1-23. Library include path addition
Chapter 1 Library
Figure 1-24. Compiler setting
Type the #include syntax into the code. Include the library into the main.c file. In the left­hand dialog, open the Sources folder of the project, and double-click the main.c file. After the main.c file opens up, include the following line in the #include section:
#include "mlib.h"
When you click the Build icon (hammer), the project will be compiled without errors.
1.4

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 or any MCUXpresso SDK example or demo application projects using Keil µVision. This example uses the default installation path (C:\NXP\RTCESL \CM4CM33CM33F_RTCESL_4.6_KEIL). If you have a different installation path, use that path instead. If any MCUXpresso SDK project is intended to use (for example hello_world project) go to Linking the files into the project chapter otherwise read next chapter.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 25
Library integration into project (Keil µVision)
1.4.1 NXP pack installation for new project (without MCUXpresso
SDK)
This example uses the NXP MKV46F256xxx15LPC55s69 part, and the default installation path (C:\NXP\RTCESL\CM4CM33CM33F_RTCESL_4.6_KEIL) is supposed. If the compiler has never been used to create any NXP MCU-based projects before, check whether the NXP MCU pack for the particular device is installed. Follow these steps:
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 (NXP) 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-25.
7. When installed, the button has the "Up to date" title. Now close the Pack Installer.
Figure 1-25. Pack Installer
MLIB User's Guide, Rev. 5, 12/2020
26 NXP Semiconductors
Chapter 1 Library
1.4.2 New project (without MCUXpresso SDK)
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-26.
Figure 1-26. Create New Project dialog
4. In the next dialog, select the Software Packs in the very first box.
5. Type 'kv4' into the Search box, so that the device list is reduced to the KV4x devices.
6. Expand the KV4x node.
7. Click the MKV46F256xxx15LPC55s69 node, and then click OK. See Figure 1-27.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 27
Library integration into project (Keil µVision)
Figure 1-27. Select Device dialog
8. In the next dialog, expand the Device node, and tick the box next to the Startup node. See Figure 1-28.
9. Expand the CMSIS node, and tick the box next to the CORE node.
Figure 1-28. Manage Run-Time Environment dialog
MLIB User's Guide, Rev. 5, 12/2020
28 NXP Semiconductors
Chapter 1 Library
10. Click OK, and a new project is created. The new project is now visible in the left­hand part of Keil µVision. See Figure 1-29.
Figure 1-29. Project
11. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog appears.
12. Select the Target tab.
13. Select Not UsedUse Single Precision in the Floating Point Hardware option. See
Figure 1-29.
MLIB User's Guide, Rev. 5, 12/2020
NXP Semiconductors 29
Library integration into project (Keil µVision)
Figure 1-30. FPU

1.4.3 PowerQuad DSP Coprocessor and Accelerator support

Some LPC platforms (LPC55S6x) contain a hardware accelerator dedicated to common calculations in DSP applications. This section shows how to turn the PowerQuad (PQ) support for a function on and off.
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-31.
3. In the Include Preprocessor Symbols text box, type the following:
• RTCESL_PQ_ON—to turn the hardware division and square root support on.
• RTCESL_PQ_OFF—to turn the hardware division and square root support off.
If neither of these two defines is defined, the hardware division and square root support is turned off by default.
MLIB User's Guide, Rev. 5, 12/2020
30 NXP Semiconductors
Loading...
+ 115 hidden pages