Automotive Math and Motor
Control Library Set for NXP
MC9S12ZVM devices
User's Guide
Rev. 24 — 26 September 2020 User guide
NXP Semiconductors Automotive Math and Motor Control
Library Set for NXP MC9S12ZVM devices
User's Guide
Automotive Math and Motor Control Library Set for NXP
MC9S12ZVM devices
All information provided in this document is subject to legal disclaimers. © NXP B.V. 2020. All rights reserved.
User guide Rev. 24 — 26 September 2020
2 / 613
Revision History
Revision Date Description
1.0 23-March-2012 Initial version.
2.0 19-February-2013 Freescale CodeWarrior Eclipse IDE support added.
3.0 3-October-2013 The user guide was updated to reflect the change of the installation
process. Changed Matlab Integration chapter (added 64-bit BAM
models). Added functions precision table. Removed floating-point
functions.
4.0 25-April-2014 Added missing descriptions in some functions, formatting changes.
Added revision history table. Removed MLIB floating-point conversion
functions.
5.0 31-March-2015 The Matlab revision, used for testing, changed to Matlab 2014a.
6.0 31-July-2015 All compilers versions were increased. Number of the significant digits of
the calculated IIR1/IIR2 coefficients in the Matlab examples for GDFLIB_
IIR1/GDFLIB_IIR2 functions was increased.
7.0 30-September-2015 Adding the chapters describing the GFLIB_SinCos function.
8.0 31-December-2015 The Service Release v1.1.3.
9.0 31-March-2016 Change from Freescale to NXP entity, Service release 1.1.4.
10.0 30-June-2016 The Service Release v1.1.5. Added new MLIB_RndSat_F16F32 function.
Added chapter about possible exceptions.
11.0 31-December-2016 The Service Release v1.1.7. Added AMCLIB_BemfObsrvDQ and
AMCLIB_TrackObsrv functions. Software License Agreement updated.
12.0 31-March-2017 The Service Release v1.1.8. Repeated sections were merged into a
common chapters in the User Guide. This approach was applied to all
AMMCLIB functions.
13.0 31-December-2017 The Service Release v1.1.11. Added new functions AMCLIB_
CurrentLoop, AMCLIB_FW, AMCLIB_FWSpeedLoop, AMCLIB_
SpeedLoop.
14.0 31-March-2018 The Service Release v1.1.12. Added new function GFLIB_VMin.
15.0 30-June-2018 The Service Release v1.1.13. Added new SetState and Init functions.
16.0 30-September-2018 The Service Release v1.1.14. Changed implementation of GFLIB_Ramp.
17.0 31-December-2018 The Service Release v1.1.15. See release notes for list of changes.
18.0 31-March-2019 The Service Release v1.1.16. See release notes for list of changes.
19.0 30-June-2019 The Service Release v1.1.17. See release notes for list of changes.
20.0 30-September-2019 The Service Release v1.1.18. See release notes for list of changes.
21.0 31-December-2019 The Service Release v1.1.19. See release notes for list of changes.
22.0 31-March-2020 The Service Release v1.1.20. See release notes for list of changes.
23.0 30-June-2020 The Service Release v1.1.21. See release notes for list of changes.
24.0 30-September-2020 The Service Release v1.1.22. See release notes for list of changes.
NXP Semiconductors Automotive Math and Motor Control
Library Set for NXP MC9S12ZVM devices
User's Guide
Automotive Math and Motor Control Library Set for NXP
MC9S12ZVM devices
All information provided in this document is subject to legal disclaimers. © NXP B.V. 2020. All rights reserved.
User guide Rev. 24 — 26 September 2020
3 / 613
1 Introduction
The aim of this document is to describe the Automotive Math and Motor Control Library
Set for NXP MC9S12ZVM devices. It describes the components of the library, its
behavior and interaction, the API and steps needed to integrate the library into the
customer project.
1.1 Architecture Overview
The Automotive Math and Motor Control Library Set for NXP MC9S12ZVM devices
consists of several sub-libraries, functionally connected as depicted in Figure 1.
Figure 1. AMMCLIB components structure
The Automotive Math and Motor Control Library Set for NXP MC9S12ZVM devices sub-
libraries are as follows:
• Mathematical Function Library (MLIB) - comprising basic mathematical operations
such as addition, multiplication, etc.
• General Function Library (GFLIB) - comprising basic trigonometric and general math
functions such as sine, cosine, tan, hysteresis, limit, etc.
• General Digital Filters Library (GDFLIB) - comprising digital IIR and FIR filters
designed to be used in a motor control application
• General Motor Control Library (GMCLIB) - comprising standard algorithms used for
motor control such as Clarke/Park transformations, Space Vector Modulation, etc.
• Advanced Motor Control Function Library (AMCLIB) - comprising advanced
algorithms used for motor control purposes
As can be seen in Figure 1, the Automotive Math and Motor Control Library Set for NXP
MC9S12ZVM devices libraries form the layer architecture where all upper libraries utilize
NXP Semiconductors Automotive Math and Motor Control
Library Set for NXP MC9S12ZVM devices
User's Guide
Automotive Math and Motor Control Library Set for NXP
MC9S12ZVM devices
All information provided in this document is subject to legal disclaimers. © NXP B.V. 2020. All rights reserved.
User guide Rev. 24 — 26 September 2020
4 / 613
the functions from MLIB library. This concept is a key factor for mathematical operations
abstractions allowing to support the highly target-optimized variants.
1.2 General Information
The Automotive Math and Motor Control Library Set for NXP MC9S12ZVM devices was
developed to support these major implementations:
• Fixed-point 32-bit fractional
• Fixed-point 16-bit fractional
With exception of those functions where the mathematical principle limits the input or
output values, these values are considered to be in the following limits:
• Fixed-point 32-bit fractional: <-1; 1-2
-31
> in Q1.31 format and with minimum positive
normalized value 2
-31
.
• Fixed-point 16-bit fractional: <-1; 1-2
-15
> in Q1.15 format and with minimum positive
normalized value 2
-15
.
Also those functions which are not relevant for particular implementation, e.g. saturated
functions or shifting for single precision floating point implementation, are not delivered
with this package. For detailed information about available functions please refer to
Section 2.1.
Note: The fixed-point 32-bit fractional and fixed-point 16-bit fractional functions are
implemented based on the unity model. Which means that the input and output numbers
are normalized to fit between the <-1; 1-2
-31
> or <-1; 1-2
-15
> range representing the
Q1.31 or Q1.15 format.
The Automotive Math and Motor Control Library Set for NXP MC9S12ZVM devices
was tested using two different test methods. To test the precision of each function
implementation, the testing based on MATLAB reference models was used. This release
was tested using the MATLAB R2019a version. To test the implementation on the
embedded side, the target-in-loop testing was performed on the Automotive Math and
Motor Control Library Set for NXP MC9S12ZVM devices. This release was tested using
MATLAB R2019a version.
1.3 Multiple Implementation Support
In order to allow the user to utilize arbitrary implementation within one user application
without any limitations, three different function call methods are supported in the
Automotive Math and Motor Control Library Set for NXP MC9S12ZVM devices:
• Global configuration option
• Additional parameter option
• API postfix option
Each of these method calls the API postfix function. Thus, for each implementation (32-
bit fixed-point and 16-bit fixed point) only one function is available within the package.
This approach is based on ANSI-C99 ISO/IEC 9899:1999 function overloading.
Global Configuration Option
This function call supports the user legacy applications, which were based on older
version of Motor Control Library. Prior to any Automotive Math and Motor Control Library
Set for NXP MC9S12ZVM devices function call using the Global configuration option,
NXP Semiconductors Automotive Math and Motor Control
Library Set for NXP MC9S12ZVM devices
User's Guide
Automotive Math and Motor Control Library Set for NXP
MC9S12ZVM devices
All information provided in this document is subject to legal disclaimers. © NXP B.V. 2020. All rights reserved.
User guide Rev. 24 — 26 September 2020
5 / 613
the SWLIBS_DEFAULT_IMPLEMENTATION macro definition has to be setup in the file
SWLIBS_Config.h.
The SWLIBS_DEFAULT_IMPLEMENTATION macro is defined in the SWLIBS_Config.h
file located in Common directory of the Automotive Math and Motor Control
Library Set for NXP MC9S12ZVM devices installation destination. The
SWLIBS_DEFAULT_IMPLEMENTATION can be defined as the one of the following
supported implementations:
• SWLIBS_DEFAULT_IMPLEMENTATION_F32 for 32-bit fixed-point implementation
• SWLIBS_DEFAULT_IMPLEMENTATION_F16 for 16-bit fixed-point implementation
After proper definition of SWLIBS_DEFAULT_IMPLEMENTATION macro the Automotive
Math and Motor Control Library Set for NXP MC9S12ZVM devices functions can be
called using standard legacy API convention, e.g. GFLIB_Sin(x).
For example if the SWLIBS_DEFAULT_IMPLEMENTATION macro definition is set to
SWLIBS_DEFAULT_IMPLEMENTATION_F32, the 32-bit fixed-point implementation of
sine function is invoked after the GFLIB_Sin(x) API call. Note that all standard legacy API
calls will invoke the 32-bit fixed-point implementation in this example.
Note: As the Automotive Math and Motor Control Library Set for NXP MC9S12ZVM
devices supports the global configuration option, it is highly recommended to copy the
SWLIBS_Config.h file to your local structure and refer the configuration to this local copy.
This approach will prevent the incorrect setup of default configuration option, in case
multiple projects with different default configuration are used.
Additional Parameter Option
In order to support the free selection of used implementation in the user application while
keeping the function name same as in standard legacy API approach, the additional
parameter option is implemented in the Automotive Math and Motor Control Library
Set for NXP MC9S12ZVM devices. In this option the additional parameter is used to
distinguish which implementation shall be invoked. There are the following possible
switches selecting the implementation:
• F32 for 32-bit fixed-point implementation
• F16 for 16-bit fixed-point implementation
For example, if the user application needs to invoke the 16-bit fixed-point implementation
of sine function, the GFLIB_Sin(x, F16) API call needs to be used. Note that there is
a possibility to call any implementation of the functions in user application without any
limitation.
API Postfix Option
In order to support the free selection of used implementation in the user application
while keeping the number of parameters same as in standard legacy API approach,
the API postfix option is implemented in the Automotive Math and Motor Control Library
Set for NXP MC9S12ZVM devices. In this option the implementation postfix is used to
distinguish which implementation shall be invoked. There are the following possible API
postfixes selecting the implementation:
• F32 for 32-bit fixed-point implementation
• F16 for 16-bit fixed-point implementation
评论0