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

• Fixed-point 32-bit fractional —<-1 ; 1 - 2

-15

> with the minimum resolution of 2

-31

> with the minimum resolution of 2

-15

-31

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

Freescale Semiconductor, Inc. 5

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

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.

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

6 Freescale Semiconductor, Inc.

Chapter 1 Library

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

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.

Freescale Semiconductor, Inc. 7

New project

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

Library integration into project (CodeWarrior™ Development Studio)

2. Choose File > New > Bareboard Project, so that the "New Bareboard Project" dialog
appears.

3. Type a name of the project, for example, MyProject01.

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.

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

8 Freescale Semiconductor, Inc.

Chapter 1 Library

Figure 1-3. Connection selection

7. From the options given, select the Simple Mixed Assembly and C language, and
click Finish. See Figure 1-4.

Figure 1-4. Language choice

The new project is now visible in the left-hand part of CodeWarrior™ Development
Studio. See Figure 1-5.

Figure 1-5. Project folder

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.

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

Freescale Semiconductor, Inc. 9

Library integration into project (CodeWarrior™ Development Studio)

2. Expand the Resource node and click Linked Resources. See Figure 1-6.

Figure 1-6. Project properties

3. Click the 'New…' button on the right-hand side.

4. In the dialog that appears (see Figure 1-7), type this variable name into the Name
box: FSLESL_LOC

5. Select the library parent folder by clicking 'Folder…' or just typing the following
path into the Location box: C:\Freescale\FSLESL\DSP56800E_FSLESL_4.2_CW
and click OK.

6. Click OK in the previous dialog.

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

10 Freescale Semiconductor, Inc.

Figure 1-7. New variable

Chapter 1 Library

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

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

Freescale Semiconductor, Inc. 11

Library integration into project (CodeWarrior™ Development Studio)

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.

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

12 Freescale Semiconductor, Inc.

Chapter 1 Library

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

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

Freescale Semiconductor, Inc. 13

Library integration into project (CodeWarrior™ Development Studio)

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.

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

14 Freescale Semiconductor, Inc.

Figure 1-12. Library include path addition

Chapter 1 Library

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.

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

GMCLIB_ClarkInv

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 User's Guide, Rev. 2, 10/2015

18 Freescale Semiconductor, Inc.

Chapter 2 Algorithms in detail

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

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);
}

Function use

/* Periodical function or interrupt */
void Isr(void)
{
/* Inverse Clarke Transformation calculation */
GMCLIB_ClarkInv_F16(&sAlphaBeta, &sAbc);
}

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

Freescale Semiconductor, Inc. 19

GMCLIB_Park

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 User's Guide, Rev. 2, 10/2015

20 Freescale Semiconductor, Inc.

Chapter 2 Algorithms in detail

2.3.3 Function use

The use of the GMCLIB_Park function is shown in the following example:

#include "gmclib.h"

static GMCLIB_2COOR_ALBE_T_F16 sAlphaBeta;
static GMCLIB_2COOR_DQ_T_F16 sDQ;
static GMCLIB_2COOR_SINCOS_T_F16 sAngle;

void Isr(void);

void main(void)
{
/* Alpha, Beta structure initialization */
sAlphaBeta.f16Alpha = FRAC16(0.0);
sAlphaBeta.f16Beta = FRAC16(0.0);

/* Angle structure initialization */
sAngle.f16Sin = FRAC16(0.0);
sAngle.f16Cos = FRAC16(1.0);
}

/* Periodical function or interrupt */
void Isr(void)
{
/* Park Transformation calculation */
GMCLIB_Park_F16(&sAlphaBeta, &sAngle, &sDQ);
}

2.4

GMCLIB_ParkInv

The GMCLIB_ParkInv function calculates the Park transformation, which transforms
values (flux, voltage, current) from the rotating two-phase (d-q) orthogonal coordinate
system to the stationary two-phase (α-β) coordinate system, according to the following
equations:

Equation 8

Equation 9

where:

• θ is the position (angle)

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

Freescale Semiconductor, Inc. 21

GMCLIB_ParkInv

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 GMCLIB_ParkInv function are shown in the following
table:

Table 2-4. Function versions

Function name Input type Output type Result type

GMCLIB_ParkInv_F16 GMCLIB_2COOR_DQ_T_F16 * GMCLIB_2COOR_ALBE_T_F16 * void

GMCLIB_2COOR_SINCOS_T_F16 *

Inverse Park transformation of a 16-bit fractional two-phase rotating system input to a 16-bit
fractional two-phase stationary 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.4.2 Declaration

The available GMCLIB_ParkInv functions have the following declarations:

void GMCLIB_ParkInv_F16(const GMCLIB_2COOR_DQ_T_F16 *psIn, const GMCLIB_2COOR_SINCOS_T_F16
*psAnglePos, GMCLIB_2COOR_ALBE_T_F16 *psOut)

2.4.3

The use of the GMCLIB_ParkInv function is shown in the following example:

#include "gmclib.h"

static GMCLIB_2COOR_ALBE_T_F16 sAlphaBeta;
static GMCLIB_2COOR_DQ_T_F16 sDQ;
static GMCLIB_2COOR_SINCOS_T_F16 sAngle;

void Isr(void);

void main(void)
{
/* D, Q structure initialization */
sDQ.f16D = FRAC16(0.0);
sDQ.f16Q = FRAC16(0.0);

/* Angle structure initialization */
sAngle.f16Sin = FRAC16(0.0);
sAngle.f16Cos = FRAC16(1.0);
}

Function use

/* Periodical function or interrupt */

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

22 Freescale Semiconductor, Inc.

Chapter 2 Algorithms in detail

void Isr(void)
{
/* Inverse Park Transformation calculation */
GMCLIB_ParkInv_F16(&sDQ, &sAngle, &sAlphaBeta);
}

2.5 GMCLIB_DecouplingPMSM

The GMCLIB_DecouplingPMSM function calculates the cross-coupling voltages to
eliminate the d-q axis coupling that causes nonlinearity of the control.

The d-q model of the motor contains cross-coupling voltage that causes nonlinearity of
the control. Figure 2-1 represents the d-q model of the motor that can be described using
the following equations, where the underlined portion is the cross-coupling voltage:

Equation 10

where:

• ud, uq are the d and q voltages

• id, iq are the d and q currents

• Rs is the stator winding resistance

• Ld, Lq are the stator winding d and q inductances

• ωel is the electrical angular speed

• ψr is the rotor flux constant

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

Freescale Semiconductor, Inc. 23

GMCLIB_DecouplingPMSM

Figure 2-1. The d-q PMSM model

To eliminate the nonlinearity, the cross-coupling voltage is calculated using the

GMCLIB_DecouplingPMSM algorithm, and feedforwarded to the d and q voltages. The

decoupling algorithm is calculated using the following equations:

Equation 11

where:

• ud, uq are the d and q voltages; inputs to the algorithm

• u

ddec

, u

are the d and q decoupled voltages; outputs from the algorithm

qdec

The fractional representation of the d-component equation is as follows:

Equation 12

The fractional representation of the q-component equation is as follows:

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

24 Freescale Semiconductor, Inc.