NXP Semiconductors DSP56800E User manual

GMCLIB User's Guide
DSP56800E
Document Number: DSP56800EGMCLIBUG
Rev. 2, 10/2015

GMCLIB User's Guide, Rev. 2, 10/2015
2 Freescale Semiconductor, Inc.

Contents
Section number Title Page
Chapter 1
Library
1.1 Introduction.................................................................................................................................................................... 5
1.2 Library integration into project (CodeWarrior™ Development Studio) .......................................................................7
Chapter 2
Algorithms in detail
2.1 GMCLIB_Clark..............................................................................................................................................................17
2.2 GMCLIB_ClarkInv........................................................................................................................................................ 18
2.3 GMCLIB_Park............................................................................................................................................................... 20
2.4 GMCLIB_ParkInv..........................................................................................................................................................21
2.5 GMCLIB_DecouplingPMSM........................................................................................................................................ 23
2.6 GMCLIB_ElimDcBusRipFOC...................................................................................................................................... 27
2.7 GMCLIB_ElimDcBusRip.............................................................................................................................................. 31
2.8 GMCLIB_SvmStd..........................................................................................................................................................36
2.9 GMCLIB_SvmIct...........................................................................................................................................................51
2.10 GMCLIB_SvmU0n........................................................................................................................................................ 55
2.11 GMCLIB_SvmU7n........................................................................................................................................................ 59
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 3

GMCLIB User's Guide, Rev. 2, 10/2015
4 Freescale Semiconductor, Inc.

Chapter 1
Library
1.1 Introduction
1.1.1 Overview
This user's guide describes the General Motor Control Library (GMCLIB) for the family
of DSP56800E core-based digital signal controllers. This library contains optimized
functions.
1.1.2 Data types
GMCLIB 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-15> with the minimum resolution of 2-15
•Fixed-point 32-bit fractional —<-1 ; 1 - 2-31> with the minimum resolution of 2-31
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 5

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
1.1.3 API definition
GMCLIB 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
GMCLIB for the DSP56800E core is written in assembly language with C-callable
interface. The library is built and tested using the following compilers:
• CodeWarrior™ Development Studio
For the CodeWarrior™ Development Studio, the library is delivered in the gmclib.lib
file.
Introduction
GMCLIB User's Guide, Rev. 2, 10/2015
6 Freescale Semiconductor, Inc.

The interfaces to the algorithms included in this library are combined into a single public
interface include file, gmclib.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 require the core saturation mode to be turned off, otherwise the
results can be incorrect. Several specific library functions are immune to the setting
of the saturation mode.
3. The library functions round the result (the API contains Rnd) to the nearest (two's
complement rounding) or to the nearest even number (convergent round). The mode
used depends on the core option mode register (OMR) setting. See the core manual
for details.
4. All non-inline functions are implemented without storing any of the volatile registers
(refer to the compiler manual) used by the respective routine. Only the non-volatile
registers (C10, D10, R5) are saved by pushing the registers on the stack. Therefore, if
the particular registers initialized before the library function call are to be used after
the function call, it is necessary to save them manually.
1.2 Library integration into project (CodeWarrior™
Development Studio)
This section provides a step-by-step guide to quickly and easily integrate the GMCLIB
into an empty project using CodeWarrior™ Development Studio. This example uses the
MC56F8257 part, and the default installation path (C:\Freescale\FSLESL
\DSP56800E_FSLESL_4.2) is supposed. If you have a different installation path, you
must use that path instead.
1.2.1 New project
To start working on an application, create a new project. If the project already exists and
is open, skip to the next section. Follow the steps given below to create a new project.
1. Launch CodeWarrior™ Development Studio.
Chapter 1 Library
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 7

2. Choose File > New > Bareboard Project, so that the "New Bareboard Project" dialog
appears.
3. Type a name of the project, for example, MyProject01.
4. If you don't use the default location, untick the “Use default location” checkbox, and
type the path where you want to create the project folder; for example, C:
\CWProjects\MyProject01, and click Next. See Figure 1-1.
Figure 1-1. Project name and location
5. Expand the tree by clicking the 56800/E (DSC) and MC56F8257. Select the
Application option and click Next. See Figure 1-2.
Figure 1-2. Processor selection
6. Now select the connection that will be used to download and debug the application.
In this case, select the option P&E USB MultiLink Universal[FX] / USB MultiLink
and Freescale USB TAP, and click Next. See Figure 1-3.
Library integration into project (CodeWarrior™ Development Studio)
GMCLIB User's Guide, Rev. 2, 10/2015
8 Freescale Semiconductor, Inc.

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

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

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

Figure 1-8. Folder link
Figure 1-9. Projects libraries paths
1.2.4 Library path setup
GMCLIB requires MLIB and GFLIB to be included too. Therefore, the following steps
show the inclusion of all dependent modules.
1. Right-click the MyProject01 node in the left-hand part and click Properties, or select
Project > Properties from the menu. A dialog with the project properties appears.
Library integration into project (CodeWarrior™ Development Studio)
GMCLIB User's Guide, Rev. 2, 10/2015
12 Freescale Semiconductor, Inc.

2. Expand the C/C++ Build node, and click Settings.
3. In the right-hand tree, expand the DSC Linker node, and click Input. See Figure 1-11.
4. In the third dialog Additional Libraries, click the 'Add…' icon, and a dialog appears.
5. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding one of the following:
• ${FSLESL_LOC}\MLIB\mlib_SDM.lib—for small data model projects
• ${FSLESL_LOC}\MLIB\mlib_LDM.lib—for large data model projects
6. Tick the box Relative To, and select FSLESL_LOC next to the box. See Figure 1-9.
Click OK.
7. Click the 'Add…' icon in the third dialog Additional Libraries.
8. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding one of the following:
• ${FSLESL_LOC}\GFLIB\gflib_SDM.lib—for small data model projects
• ${FSLESL_LOC}\GFLIB\gflib_LDM.lib—for large data model projects
9. Tick the box Relative To, and select FSLESL_LOC next to the box. Click OK.
10. Click the 'Add…' icon in the Additional Libraries dialog.
11. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding one of the following:
• ${FSLESL_LOC}\GMCLIB\gmclib_SDM.lib—for small data model projects
• ${FSLESL_LOC}\GMCLIB\gmclib_LDM.lib—for large data model projects
12. Tick the box Relative To, and select FSLESL_LOC next to the box. Click OK.
13. Now, you will see the libraries added in the box. See Figure 1-11.
Figure 1-10. Library file inclusion
Chapter 1 Library
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 13

Figure 1-11. Linker setting
14. In the tree under the DSC Compiler node, click Access Paths.
15. In the Search User Paths dialog (#include “…”), click the 'Add…' icon, and a dialog
will appear.
16. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\MLIB\include.
17. Tick the box Relative To, and select FSLESL_LOC next to the box. See Figure 1-12.
Click OK.
18. Click the 'Add…' icon in the Search User Paths dialog (#include “…”).
19. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\GFLIB\include.
20. Tick the box Relative To, and select FSLESL_LOC next to the box. Click OK.
21. Click the 'Add…' icon in the Search User Paths dialog (#include “…”).
22. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\GMCLIB\include.
23. Tick the box Relative To, and select FSLESL_LOC next to the box. Click OK.
24. Now you will see the paths added in the box. See Figure 1-13. Click OK.
Library integration into project (CodeWarrior™ Development Studio)
GMCLIB User's Guide, Rev. 2, 10/2015
14 Freescale Semiconductor, Inc.

Figure 1-12. Library include path addition
Figure 1-13. Compiler setting
The final step is typing the #include syntax into the code. Include the library into the
main.c file. In the left-hand dialog, open the Sources folder of the project, and double-
click the main.c file. After the main.c file opens up, include the following lines into the
#include section:
#include "mlib.h"
#include "gflib.h"
#include "gmclib.h"
When you click the Build icon (hammer), the project will be compiled without errors.
Chapter 1 Library
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 15

Library integration into project (CodeWarrior™ Development Studio)
GMCLIB User's Guide, Rev. 2, 10/2015
16 Freescale Semiconductor, Inc.

Chapter 2
Algorithms in detail
2.1 GMCLIB_Clark
The GMCLIB_Clark function calculates the Clarke transformation, which is used to
transform values (flux, voltage, current) from the three-phase coordinate system to the
two-phase (α-β) orthogonal coordinate system, according to the following equations:
Equation 1
Equation 2
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 saturate.
The available versions of the GMCLIB_Clark function are shown in the following table:
Table 2-1. Function versions
Function name Input type Output type Result type
GMCLIB_Clark_F16 GMCLIB_3COOR_T_F16 * GMCLIB_2COOR_ALBE_T_F16 * void
Clarke transformation of a 16-bit fractional three-phase system input to a 16-bit fractional two-
phase system. The input and output are within the fractional range <-1 ; 1).
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 17

2.1.2 Declaration
The available GMCLIB_Clark functions have the following declarations:
void GMCLIB_Clark_F16(const GMCLIB_3COOR_T_F16 *psIn, GMCLIB_2COOR_ALBE_T_F16 *psOut)
2.1.3 Function use
The use of the GMCLIB_Clark function is shown in the following example:
#include "gmclib.h"
static GMCLIB_2COOR_ALBE_T_F16 sAlphaBeta;
static GMCLIB_3COOR_T_F16 sAbc;
void Isr(void);
void main(void)
{
/* ABC structure initialization */
sAbc.f16A = FRAC16(0.0);
sAbc.f16B = FRAC16(0.0);
sAbc.f16C = FRAC16(0.0);
}
/* Periodical function or interrupt */
void Isr(void)
{
/* Clarke Transformation calculation */
GMCLIB_Clark_F16(&sAbc, &sAlphaBeta);
}
2.2 GMCLIB_ClarkInv
The GMCLIB_ClarkInv function calculates the Clarke transformation, which is used to
transform values (flux, voltage, current) from the two-phase (α-β) orthogonal coordinate
system to the three-phase coordinate system, according to the following equations:
Equation 3
Equation 4
Equation 5
GMCLIB_ClarkInv
GMCLIB User's Guide, Rev. 2, 10/2015
18 Freescale Semiconductor, Inc.

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 <-1 ; 1). The result may saturate.
The available versions of the GMCLIB_ClarkInv function are shown in the following
table:
Table 2-2. Function versions
Function name Input type Output type Result type
GMCLIB_ClarkInv_F16 GMCLIB_2COOR_ALBE_T_F16 * GMCLIB_3COOR_T_F16 * void
Inverse Clarke transformation with a 16-bit fractional two-phase system input and a 16-bit
fractional three-phase output. The input and output are within the fractional range <-1 ; 1).
2.2.2 Declaration
The available GMCLIB_ClarkInv functions have the following declarations:
void GMCLIB_ClarkInv_F16(const GMCLIB_2COOR_ALBE_T_F16 *psIn, GMCLIB_3COOR_T_F16 *psOut)
2.2.3 Function use
The use of the GMCLIB_ClarkInv function is shown in the following example:
#include "gmclib.h"
static GMCLIB_2COOR_ALBE_T_F16 sAlphaBeta;
static GMCLIB_3COOR_T_F16 sAbc;
void Isr(void);
void main(void)
{
/* Alpha, Beta structure initialization */
sAlphaBeta.f16Alpha = FRAC16(0.0);
sAlphaBeta.f16Beta = FRAC16(0.0);
}
/* Periodical function or interrupt */
void Isr(void)
{
/* Inverse Clarke Transformation calculation */
GMCLIB_ClarkInv_F16(&sAlphaBeta, &sAbc);
}
Chapter 2 Algorithms in detail
GMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc. 19

2.3 GMCLIB_Park
The GMCLIB_Park function calculates the Park transformation, which transforms values
(flux, voltage, current) from the stationary two-phase (α-β) orthogonal coordinate system
to the rotating two-phase (d-q) orthogonal coordinate system, according to the following
equations:
Equation 6
Equation 7
where:
•θis the position (angle)
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 saturate.
The available versions of the GMCLIB_Park function are shown in the following table:
Table 2-3. Function versions
Function name Input type Output type Result type
GMCLIB_Park_F16 GMCLIB_2COOR_ALBE_T_F16 * GMCLIB_2COOR_DQ_T_F16 * void
GMCLIB_2COOR_SINCOS_T_F16 *
The Park transformation of a 16-bit fractional two-phase stationary system input to a 16-bit
fractional two-phase rotating system, using a 16-bit fractional angle two-component (sin / cos)
position information. The inputs and the output are within the fractional range <-1 ; 1).
2.3.2 Declaration
The available GMCLIB_Park functions have the following declarations:
void GMCLIB_Park_F16(const GMCLIB_2COOR_ALBE_T_F16 *psIn, const GMCLIB_2COOR_SINCOS_T_F16
*psAnglePos, GMCLIB_2COOR_DQ_T_F16 *psOut)
GMCLIB_Park
GMCLIB User's Guide, Rev. 2, 10/2015
20 Freescale Semiconductor, Inc.