Freescale Embedded Software Library S08cache.freescale.com/files/microcontrollers/doc/ref_manual/FSLESLS... · Freescale Embedded Software Library S08 API Reference Manual, Rev. 1

Freescale Embedded Software Library S08API Reference Manual

Document Number: FSLESLS08APIRMRev. 1

10/2009

How to Reach Us:

Home Page:www.freescale.com

E-mail:[email protected]

USA/Europe or Locations Not Listed:Freescale SemiconductorTechnical Information Center, CH3701300 N. Alma School RoadChandler, Arizona 85224+1-800-521-6274 or [email protected]

Europe, Middle East, and Africa:Freescale Halbleiter Deutschland GmbHTechnical Information CenterSchatzbogen 781829 Muenchen, Germany+44 1296 380 456 (English)+46 8 52200080 (English)+49 89 92103 559 (German)+33 1 69 35 48 48 (French)[email protected]

Japan:Freescale Semiconductor Japan Ltd.HeadquartersARCO Tower 15F1-8-1, Shimo-Meguro, Meguro-ku,Tokyo 153-0064, Japan0120 191014 or +81 3 5437 [email protected]

Asia/Pacific:Freescale Semiconductor China Ltd.Exchange Building 23FNo. 118 Jianguo RoadChaoyang DistrictBeijing 100022China +86 10 5879 8000 [email protected]

For Literature Requests Only:Freescale Semiconductor Literature Distribution Center1-800-441-2447 or 303-675-2140Fax: [email protected]

Information in this document is provided solely to enable system and software implementers to use Freescale Semiconductor products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits or integrated circuits based on the information in this document.

Freescale Semiconductor reserves the right to make changes without further notice to any products herein. Freescale Semiconductor makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale Semiconductor 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 Semiconductor 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 Semiconductor does not convey any license under its patent rights nor the rights of others. Freescale Semiconductor products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Freescale Semiconductor product could create a situation where personal injury or death may occur. Should Buyer purchase or use Freescale Semiconductor products for any such unintended or unauthorized application, Buyer shall indemnify and hold Freescale Semiconductor and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Freescale Semiconductor was negligent regarding the design or manufacture of the part.

Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners.

© 1994-2008 ARC™ International. All rights reserved.

© Freescale Semiconductor, Inc. 2009. All rights reserved.

Document Number: FSLESLS08APIRMRev. 110/2009

Freescale Embedded Software Library S08 API Reference Manual, Rev. 1

iii Freescale Semiconductor

Revision History

To provide the most up-to-date information, the revision of our documents on the World Wide Web will be the most current. Your printed copy may be an earlier revision. To verify you have the latest information available, refer to:

http://www.freescale.com

The following revision history table summarizes changes contained in this document.

Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc.© Freescale Semiconductor, Inc., 2009. All rights reserved.

RevisionNumber

RevisionDate Description of Changes

Rev. 1 10/2009 Launch Release

http://www.freescale.com


Freescale Semiconductor iv

Chapter 1Before You Begin

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.2 Library Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11.3 Reference Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.4 Supported Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.5 Library Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.6 Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21.7 Function Listing Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

1.7.1 Function Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31.8 Data Types Used in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Chapter 2S08math Functions

2.1 Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12.2 S08math Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22.3 S08math Functions Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.3.1 add8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-42.3.2 add16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52.3.3 add32_16_32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-62.3.4 uadd8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72.3.5 uadd16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82.3.6 uadd32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92.3.7 uadd32_64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102.3.8 sub8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-112.3.9 sub16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-122.3.10 usub8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-132.3.11 usub16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-142.3.12 mul8_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-152.3.13 umul16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-162.3.14 umul32_32_64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-172.3.15 udiv16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-182.3.16 shl16_u8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-192.3.17 shr16_u8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-202.3.18 ushl16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-212.3.19 ushr16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-222.3.20 neg8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-232.3.21 neg16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-242.3.22 abs16_8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-252.3.23 fshl8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-262.3.24 lim32_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-272.3.25 sinLut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28


v Freescale Semiconductor

Chapter 3ECLIB Functions

3.1 Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.2 ECLIB Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13.3 ECLIB Functions Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

3.3.1 ECLIB_3phaseGen16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23.3.2 ECLIB_ControllerPI16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53.3.3 ECLIB_VHzProfile16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-73.3.4 ECLIB_Ramp16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9


Freescale Semiconductor 1-1

Chapter 1 Before You Begin

1.1 OverviewThis reference manual describes the Freescale Embedded Software Library (FSLESLS08) designed to construct digital control systems for the S08 family of microcontrollers. The library contains optimized software modules implemented in assembly with a C-callable function interface.

As shown in the figure below, FSLESLS08 comprises two main function groups:• S08math functions — With the basic math primitives (S08math) for 8-bit, 16-bit, 32-bit and 64-bit

variables. Basic math functions supported are:— Addition— Subtraction— Multiplication— Shifting operations — Absolute value and limitation

• Embedded Control Functions (ECLIB) — ECLIB functions support:— PI controller— Ramps— V/Hz profile— Sine generator

Figure 1-1. Freescale Embedded Software Library

1.2 Library FeaturesFSLESLS08 supports HCS08 core-based microcontroller. FSLESLS08 library features are:

• Written in the assembly language• Optimized for speed and size• Supplied as binary files• Easy to link to the project

Before You Begin


1-2 Freescale Semiconductor

1.3 Reference MaterialUse this manual in conjunction with:

• HC08ASMRM — HC(S)08/RS08 Assembler Manual for Microcontrollers• 950-00087 — CodeWarrior Development Studio for Microcontrollers v6.2

For information about FSLESL libraries for other microcontrollers, refer to:• MCF51_GFLIB — General Functions Library• MCF51_MCLIB — Motor Control Library• MCF51_GDFLIB — General Digital Filters Library

1.4 Supported CompilersThe FSLESLS08 is written in the assembly language with a C-callable interface. The embedded control functions are written in C-language using the S08math functions. The library is built and tested using the following compiler:

CodeWarrior™ Development Studio V6.2

1.5 Library InstallationTo fully use FSLESLS08 library, you need to install the CodeWarrior tools prior to the library. If FSLESLS08 library is installed prior to CodeWarrior tools, you can only browse the installed software package, but will not be able to run the code.

To install FSLESLS08:1. Copy the required files to the destination hard drive.2. Check if CodeWarrior is installed.3. Create a shortcut under the Start > Programs menu.4. Execute the FSLESLS08.exe file.5. Follow the installation instructions that appear.

1.6 Library IntegrationTo add the FSLESLS08 library to a new CodeWarrior project, add the particular library source and header files to the project according to the requirements of the application. For more information, refer to Section 2.1, “Library Integration.”

1.7 Function Listing FormatThis is the general format of an entry for a function or macro.

Before You Begin



1.7.1 Function Name

Description

Provides a brief description of the function or macro. It explains algorithms being used by functions or macros.

Special Issues

Specifies special assumptions that are mandatory for the correct function calculation. For example, saturation, rounding, and so on.

Implementation

Specifies whether a call of the function generates a library function call or a macro expansion.

Implementation Code

Provides one or more examples of the use of the function. The examples are often fragments of code (not completed programs) for the illustration purpose.

Performance

Specifies the actual requirements of the function or macro in terms of required code memory, data memory, and number of clock cycles to execute.

Arguments

Describes input arguments to a function or macro.

NOTEThe Arguments section is available for a few functions only.

Before You Begin



1.8 Data Types Used in FunctionsTable 1-1 shows the data types supported by the S08math functions.

Table 1-1. Data Types in FSLESLS08

Mnemonics Size Min Max Description

signed char 8 –128 127 Represents the 8-bit signed variable/value.

unsigned char 8 0 255 Represents the 8-bit unsigned variable/value.

signed int 16 –32768 32767 Represents the 16-bit signed variable/value.

unsigned int 16 0 65535 Represents the 16-bit unsigned variable/value.

signed long 32 –2^31 2^31 Represents the 32-bit signed variable/value.

unsigned long 32 0 2^32 Represents the 32-bit unsigned variable/value.

unsigned longUINT64[2]

64 0 2^64 Own type to represent the unsigned 64-bit variable/value.



Chapter 2 S08math Functions

2.1 Library IntegrationTo add S08math functions from the FSLESLS08 library to a new CodeWarrior project, perform the following steps:

1. Create a new empty project or add the files to your existing project. (See Figure 2-1)2. Add the source and header files (S08math.h, S08math.asm) to the project.3. The sine look-up table function has separate source and header files. To use the sinLut function,

add the source and header files (sinLut.h, sinLut.asm and sinTab180.asm) to the project.4. To use the library functions, add the following program line to the user-application source code.

#include "S08math.h"

5. Optionally include the sinLut.h if the sine function is used in your application. For details, refer to Section 2.3.25, “sinLut.”#include "sinLut.h"

Figure 2-1. FSLESLS08 Integration

S08math Functions



2.2 S08math Functions Overview

Table 2-1. S08math Functions Summary

Function

Performance

Parameter Return (Out) DescriptionCode size

(byte)

Execution (cycle)

min max

add8 16 20 22 xy

inin

signed charsigned char

signed char 8-bit signed addition with overflow control and saturation

add16 26 32 35 xy

inin

signed intsigned int

signed int 16-bit signed addition with overflow control and saturation

add32_16_32 78 79 86 xy

inin

signed longsigned int

signed long 32-bit signed addition, accumulation

uadd8 10 16 18 xy

inin

unsigned charunsigned char

unsigned char 8-bit unsigned addition with overflow control and saturation

uadd16 19 32 35 xy

inin

unsigned intunsigned int

unsigned int 16-bit unsigned addition with overflow control and saturation

uadd32 45 59 76 xy

inin

unsigned longunsigned long

unsigned long 32-bit unsigned addition with overflow control and saturation

uadd32_64 55 89 100 xy

inin/out

unsigned longUINT64[2]

void Addition of unsigned 32-bit number with unsigned 64-bit number

sub8 16 21 22 xy

inin


signed char 8-bit signed subtraction with overflow control and saturation

sub16 26 35 38 xy

inin

signed intsigned int

signed int 16-bit signed subtraction with overflow control and saturation

usub8 9 17 18 xy

inin


unsigned char 8-bit unsigned subtraction with overflow control and saturation

usub16 20 28 32 xy

inin

unsigned intunsigned int

unsigned int 16-bit unsigned subtraction with overflow control and saturation

mul8_8_16 28 45 53 xy

inin


signed int 8-bit signed multiplication with 16-bit result

S08math Functions



umul16_8_16 27 45 53 xy

inin

unsigned intunsigned char

unsigned int 16x8 unsigned fractional multiplication with 16-bit result

umul32_32_64 420 635 667 xy

inin

unsigned longunsigned long

void 32-bit unsigned multiplication with 64-bit result

udiv16_8_16 15 44 54 xy

inin


unsigned int Unsigned fractional division 16-bit value by 8-bit with 16-bit result.

shl16_u8_16 24 55 257 xshift

inin

signed intunsigned char

signed int 16-bit signed shift left with overflow control and saturation

shr16_u8_16 17 63 2877

xshift

inin

signed charunsigned char

signed int 16-bit signed shift right

ushl16_8_16 24 30 226 xshift

inin


unsigned int 16-bit unsigned shift left with overflow control and saturation

ushr16_8_16 17 30 2849

xshift

inin


unsigned int 16-bit unsigned shift right

neg8 7 25 29 x in signed char signed char 8-bit signed negation

neg16 17 39 48 x in signed int signed int 16-bit signed negation

abs16_8 11 33 35 x in signed int unsigned char Absolute value and extraction of high byte

fshl8_16 5 29 29 x in unsigned char signed int Fast instant 7-bits shift left

lim32_16 49 57 72 phase

amp

inin


signed int Limitation of signed long number in signed integer range

sinLut 25 34 39 xy

inin


signed char Look-up table sine computation

Table 2-1. (continued)S08math Functions Summary

Function

Performance

Parameter Return (Out) DescriptionCode size

(byte)

Execution (cycle)

min max

S08math Functions



2.3 S08math Functions Description

2.3.1 add8

Description

The function performs the 8-bit addition with overflow control and saturation. The 8-bit result is set at +127 on overflow, or at –128 on underflow.

Availability

This library module is available in the C-callable interface assembly format.

Special Issues

The result is saturated.

Implementation

The add8 function is implemented as a function call.

Implementation Code#include "S08math.h"

signed char x,y,z;

void main(void) { x = 50; y = -15; z = add8(x,y);}

Performance

Table 2-2. Performance of the add8 Function

Code Size (bytes) 78

Data Size (bytes) 0

Execution Clock (cycles)Min 79

Max 86

S08math Functions



2.3.2 add16

Description

The function performs the 16-bit addition with overflow control and saturation. The 16-bit result is set at +32767 on overflow, or at –32768 on underflow.

Availability


Special Issues


Implementation

The add16 function is implemented as a function call.


signed int x,y,z;

void main(void) { x = 5000; y = -15000; z = add16(x,y);}

Performance

Table 2-3. Performance of the add16 Function


Data Size (bytes) 0


Max 35

S08math Functions



2.3.3 add32_16_32

Description

The function performs the addition of signed 16-bit values with a signed 32-bit variable. The function could be used for summation and accumulation of 16-bit values to a 32-bit sum variable.

Availability


Implementation

The add32_16_32 function is implemented as a function call.


signed int x;signed long sum;

void main(void) { x = 5000; sum = 235000; sum = add32_16_32(sum,x);}

Performance

Table 2-4. Performance of the add32_16_32 Function


Data Size (bytes) 0


Max 35

S08math Functions



2.3.4 uadd8

Description

The function performs the unsigned 8-bit addition with overflow control and saturation. The 8-bit result is set at +255 on overflow.

Availability


Special Issues


Implementation

The uadd8 function is implemented as a function call.


unsigned char x,y,z;

void main(void) { x = 60; y = 200; z = uadd8(x,y);}

Performance

Table 2-5. Performance of the uadd8 Function


Data Size (bytes) 0


Max 18

S08math Functions



2.3.5 uadd16

Description


Availability


Special Issues


Implementation



unsigned int x,y,z;


Performance



Data Size (bytes) 0


Max 35

S08math Functions



2.3.6 uadd32

Description


Availability


Special Issues


Implementation



unsigned long x,y,z;


Performance



Data Size (bytes) 0


Max 35

S08math Functions



2.3.7 uadd32_64

Description

The function performs the addition of an unsigned 32-bit number with an unsigned 64-bit number. The 64-bit result is stored in y. The result is not saturated.

Availability


Implementation

The uadd32_64 function is implemented as a function call. To represent a 64-bit variable, y is defined as type UINT64 (see Data Types Used in Functions).


unsigned long x;

UINT64 y = {0,0};

void main(void) { x = 4294967290; y[0] = 0; y[1] = 67290; uadd32_64(x,y);}

Performance

An application of this special type of function is the summation of enormous numbers for further computation (integration, averaging).

Table 2-8. Performance of the uadd32_64 Function


Data Size (bytes) 0


Max 100

S08math Functions



2.3.8 sub8

Description

The function performs the 8-bit subtraction with overflow control and saturation. The 8-bit result is set at +127 on overflow, or at –128 on underflow.

Availability


Special Issues


Implementation

The sub8 function is implemented as a function call.


signed char x,y,z;

void main(void) { x = -50; y = 20; z = sub8(x,y);}

Performance

Table 2-9. Performance of the sub8 Function


Data Size (bytes) 0


Max 22

S08math Functions



2.3.9 sub16

Description

The function performs the 16-bit subtraction with overflow control and saturation. The 16-bit result is set at +32767 on overflow, or at –32768 on underflow.

Availability


Special Issues


Implementation

The sub16 function is implemented as a function call.


signed int x,y,z;

void main(void) { x = -3000; y = 8000; z = sub16(x,y);}

Performance

Table 2-10. Performance of the sub16 Function


Data Size (bytes) 0


Max 38

S08math Functions



2.3.10 usub8

Description

The function performs the unsigned 8-bit subtraction with underflow control. The 8-bit result is set at 0 on underflow.

Availability


Special Issues


Implementation

The usub8 function is implemented as a function call.


unsigned char x,y,z;

void main(void) { x = 200; y = 180; z = usub8(x,y);}

Performance

Table 2-11. Performance of the usub8 Function

Code Size (bytes) 9

Data Size (bytes) 0


Max 18

S08math Functions



2.3.11 usub16

Description

The function performs the unsigned 16-bit subtraction with underflow control. The 16-bit result is set at 0 on underflow.

Availability


Special Issues


Implementation

The usub16 function is implemented as a function call.


unsigned int x,y,z;

void main(void) { x = 5000; y = 50; z = usub16(x,y);}

Performance

Table 2-12. Performance of the usub16 Function


Data Size (bytes) 0


Max 32

S08math Functions



2.3.12 mul8_8_16

Description

The function performs the signed 8-bit multiplication with a 16-bit result.

Availability


Implementation

The mul8_8_16 function is implemented as a function call.


signed char x,y; signed int z;

void main(void) { x = -10; y = 8; z = mul8_8_16(x,y); }

Performance

Table 2-13. Performance of the mul8_8_16 Function


Data Size (bytes) 0


Max 53

S08math Functions



2.3.13 umul16_8_16

Description

The function performs the unsigned fractional 16-bit * 8-bit multiplication where the second operand is a fractional multiplier.

Availability


Implementation

The umul16_8_16 function is implemented as a function call.


signed char y; signed int x,z;

void main(void) { x = 32000; y = 255; z = umul16_8_16(x,y); }

Performance

When the fractional multiplier is at its maximum 255, the output 16-bit result never reaches 100% of the 16-bit input value. For example, for the input value 32000 and fractional the multiplier 255, the result is 31875 because the function performs: (32000*255)>>8 = (32000*255)/256 = 31875.

Table 2-14. Performance of the umul16_8_16 Function


Data Size (bytes) 0


Max 53

S08math Functions



2.3.14 umul32_32_64

Description

The function performs the unsigned 32-bit multiplication with a 64-bit result.

Availability


Implementation

The umul32_32_64 function is implemented as a function call.


unsigned long x,y;

UINT64 z = {0,0};

void main(void){ x = 4294967290; y = 1024; umul32_32_64(x,y,z);}

Performance

Table 2-15. Performance of the umul32_32_64 Function


Data Size (bytes) 0


Max 667

S08math Functions



2.3.15 udiv16_8_16

Description

The function performs the unsigned fractional division of a 16-bit value by an 8-bit value with a 16-bit result.

Availability


Special Issues

The result is saturated. 2

Implementation

The udiv16_8_16 function is implemented as a function call.


unsigned char y; unsigned int x,z;

void main(void) { x = 16620; y = 127; z = udiv16_8_16(x,y);}

Performance

Table 2-16. Performance of the udiv16_8_16 Function


Data Size (bytes) 0


Max 54

S08math Functions



2.3.16 shl16_u8_16

Description

The function performs the shift left of a signed 16-bit input variable. The 16-bit result is set at +32767 on overflow, or at –32768 on underflow.

Availability


Implementation

The shl16_u8_16 function is implemented as a function call.


unsigned char shift; signed int x,z;

void main(void) { x = -3200; shift = 1; z = shl16_u8_16(x,shift); }

Performance

Table 2-17. Performance of the shl16_u8_16 Function


Data Size (bytes) 0


Max 257

S08math Functions



2.3.17 shr16_u8_16

Description

The function performs the shift right of a signed 16-bit input variable.

Availability


Implementation

The shr16_u8_16 function is implemented as a function call.


unsigned char shift; signed int x,z;

void main(void) { x = -3200; shift = 1; z = shr16_u8_16(x,shift); }

Performance

Table 2-18. Performance of the shr16_u8_16 Function


Data Size (bytes) 0


Max 2877

S08math Functions



2.3.18 ushl16_8_16

Description

The function performs the shift left of an unsigned 16-bit input variable. The result is saturated.

Availability


Implementation

The ushl16_8_16 function is implemented as a function call.


unsigned char shift; unsigned int x,z;

void main(void) { x = 32000; shift = 1; z = ushl16_8_16(x,shift); }

Performance

Table 2-19. Performance of the ushl16_8_16 Function


Data Size (bytes) 0


Max 226

S08math Functions



2.3.19 ushr16_8_16

Description

The function performs the shift right of an unsigned 16-bit input variable.

Availability


Implementation

The ushr16_8_16 function is implemented as a function call.


unsigned char shift; unsigned int x,z;

void main(void) { x = 32000; shift = 1; z = ushr16_8_16(x,shift); }

Performance

Table 2-20. Performance of the ushr16_8_16 Function


Data Size (bytes) 0


Max 2849

S08math Functions



2.3.20 neg8

Description

The function performs the negation of an 8-bit input variable.

Availability


Implementation

The neg8 function is implemented as a function call.


signed char x,z;

void main(void) { x = -128; z = neg8(x);}

Performance

Table 2-21. Performance of the neg8 Function

Code Size (bytes) 7

Data Size (bytes) 0


Max 29

S08math Functions



2.3.21 neg16

Description

The function performs the negation of a 16-bit input variable.

Availability


Implementation

The neg16 function is implemented as a function call.


signed int x,z;

void main(void) { x = 5000; z = neg16(x);}

Performance

Table 2-22. Performance of the neg16 Function


Data Size (bytes) 0


Max 31

S08math Functions



2.3.22 abs16_8

Description

The function performs the absolute value of a 16-bit input variable and extraction of the high byte.

Availability


Implementation

The abs16_8 function is implemented as a function call.


signed int x;unsigned char z;

void main(void) { x = -3000; z = abs16_8(x);}

Performance

Table 2-23. Performance of the abs16_8 Function


Data Size (bytes) 0


Max 35

S08math Functions



2.3.23 fshl8_16

Description

The function performs a fast instant 7-bits shift left.

Availability


Implementation

The fshl8_16 function is implemented as a function call.


signed int z;unsigned char x;

void main(void) { x = 30; z = fshl8_16(x);}

Performance

Table 2-24. Performance of the fshl8_16 Function

Code Size (bytes) 5

Data Size (bytes) 0


Max 29

S08math Functions



2.3.24 lim32_16

Description

The function performs limitation of an input signed 32-bit variable in the signed 16-bit range.

Availability


Implementation

The lim32_16 function is implemented as a function call.


signed int z;signed long x;

void main(void) { x = 39000; z = lim32_16(x);}

Performance

Table 2-25. Performance of the lim32_16 Function


Data Size (bytes) 0


Max 72

S08math Functions



2.3.25 sinLut

Description

The function performs the look-up table sine calculation.

Availability


Implementation

The sinLut function is implemented as a function call. The sinLut function has its source and header files. The following source and header files must be integrated into the project:

• sinLut.asm• sinLut.h• sinTab180.asm

Implementation Code#include "sinLut.h"

unsigned char amplitude,phase;

signed int z;

void main(void) { amplitude = 255; phase = 120; z = sinLut(phase,amplitude);}

Figure 2-2. sinLut Performance Example

S08math Functions



Arguments

The input parameter amplitude multiplies a fetched value from the table, where the position in the table is defined by the phase parameter. Half of the sine is stored in the sinTab180.asm with an amplitude corresponding to 127, which means that the maximum possible amplitude of the output sine could be 127*255.

Table 2-26. Function Parameters Description

Performance

Input Parameter Size Meaning

amplitude 0...255 0...100%

phase 0...255 0...359°

Table 2-27. Performance of the sinLut Function


Data Size (bytes) 128


Max 39

S08math Functions





Chapter 3 ECLIB Functions

3.1 Library IntegrationThe ECLIB functions from the FSLESLS08 are easily integrated into your new or existing project by the following the steps described in the Implementation section in each function.

Each function has its own header and source file. Some ECLIB functions need to integrate the S08math or sine function source and header. The ECLIB functions application area is for general embedded control systems, and some of these functions are designed especially for motor control applications.

3.2 ECLIB Functions Overview

Table 3-1. ECLIB Functions

Function Parameter Return Description

ECLIB_3phaseGen16 amplitudeactualPhase

phaseAphaseBphaseC

inin

outoutout

unsigned charunsigned charunsigned intunsigned intunsigned int

structure Calculates the 3-phase sine wave generator.

ECLIB_ControllerPI16 errorpiParams

inin/out

signed intstructure

signed int Calculates the standard 16-bit PI (Proportional-Integral)

controller with limitation.

ECLIB_VHzProfile16 vhzTablefrequency

inin

structuresigned int

signed int Calculates Volt per Hertz profile.

ECLIB_Ramp16 incrementreqValueactValue

inin

out

signed intsigned intsigned int

signed int Increments or decrements the output value by the step defined by increment to bring the actual value closer to the required value.

ECLIB Functions



3.3 ECLIB Functions Description

3.3.1 ECLIB_3phaseGen16

Description

The function performs as a 3-phase sine generator. ECLIB_3phaseGen16 uses the sinLut function. The generator has two inputs and three outputs.

• Input — The input variable amplitude defines the amplitude of the generated output signals. The second input phase defines the angle of the first phase, and the angles of the other two phases are recalculated from the first phase.

• Output — Outputs of the generator are processed with an offset of 32768 at the midpoint of the 2^16 scale. It is useful to use the generator outputs in this format for PWM generation. The output 3-phase system is accessible through a structure (refer to the Implementation Code).

Availability

This library module is available in the C-callable interface format.

Implementation

The ECLIB_3phaseGen16 function is implemented as a function call.

To implement ECLIB_3phaseGen16:1. Include ECLIB_3phaseGen16.h. 2. Insert the files sinLut.asm, sinLut.h, sinTab180.asm, and ECLIB_3phaseGen16.c into the project. 3. Initialize the ECLIB_s3PhaseSystem structure.

Implementation Code#include "ECLIB_3phaseGen16.h"

unsigned char amp,phase;

static ECLIB_s3PhaseSystem pOutputSystem; /* pointer to output phases */

unsigned int phA,phB,phC;

void main(void) { amp = 255; phase = 64; ECLIB_3phaseGen16(amp,phase,&pOutputSystem); phA = pOutputSystem.phaseA; phB = pOutputSystem.phaseB; phC = pOutputSystem.phaseC;}

ECLIB Functions



ArgumentsTable 3-2. Function Parameters Description

Performance

Figure 3-1. Output Waveforms for 100% Amplitude

Parameter Size Meaning

amplitude unsigned char 0...100%

phase unsigned char 0...359°

pOutputSystem.phaseA unsigned int 0...100%

pOutputSystem.phaseB unsigned int 0...100%

pOutputSystem.phaseC unsigned int 0...100%

Table 3-3. Performance of the ECLIB_3phaseGen16 function




Max 215

ECLIB Functions



Figure 3-2. Output Waveforms for 50% Amplitude

ECLIB Functions



3.3.2 ECLIB_ControllerPI16

Description

The function performs a parallel form of a 16-bit Proportional-Integral Controller with output limitation. The ECLIB_ControllerPI16 uses several functions from S08math, especially the fractional multiplication umul16_8_16, negation neg16, 16-bit shifts, and add16. Input parameters are accessible through the structure (see the Implementation Code).

Availability


Implementation

The ECLIB_ControllerPI16 function is implemented as a function call.

To implement ECLIB_ControllerPI16:1. Include ECLIB_ControllerPI16.h. 2. Insert the files S08math.asm, S08math.h, ECLIB_ControllerPI16.c into the project. 3. Initialize the ECLIB_sPIparams structure.

Implementation Code#include "ECLIB_ControllerPI16.h"

signed int error,output;

static ECLIB_sPIparams pPIparams; /* pointer to output phases */

void main(void) { error = 512;

pPIparams.propGain = 128; pPIparams.propGainShift = 0; pPIparams.intGain = 120; pPIparams.intGainShift = -4; pPIparams.upperLimit = 2000; pPIparams.lowerLimit = -2000; pPIparams.integralPortionK_1 = 0;

output = ECLIB_ControllerPI16 (error, &pPIparams);}

ArgumentsTable 3-4. Function Parameters Description


pPIparams.propGain unsigned char 0...100%

pPIparams.propGainShiftsigned char positive value - shift left

negative value - shift right

ECLIB Functions



PerformanceTable 3-5. Performance of the ECLIB_ControllerPI16 Function

ECLIB_ControllerPI16 performance is almost dependent on shift values. For a general shift value in the range (–5, 5), the execution is between 607 to 720 cycles. This version of the PI controller brings a compromise between execution time and resolution using an 8-bit MCU.

Figure 3-3. PI Controller Performance Example

pPIparams.intGain unsigned char 0...100%

pPIparams.intGainShiftsigned char positive value - shift left

negative value - shift right

pPIparams.upperLimit signed int upper limitation value

pPIparams.lowerLimit signed int lower limitation value

pPIparams.integralPortionK_1 signed int integral portion sum




Max 3474


ECLIB Functions



3.3.3 ECLIB_VHzProfile16

Description

ECLIB_VHzProfile16 calculates the required phase voltage amplitude based on the V/Hz motor specific parameters and the required frequency. The function uses the abs16_8 function and fshl8_16 from S08math.

An important element of this function is the creation of the V/Hz table. This is done by using ECLIB_VHZ_CREATE_TABLE as shown in the Implementation Code. The input parameters of the table (V_BOOST, V_BASE, F_BOOST, F_BASE) are scaled to the range <0,100%> to a nominal voltage or frequency. The Volt per Hertz profile, with the main table parameters, is illustrated in Figure 3-4.

Availability


Implementation

The ECLIB_VHzProfile16 function is implemented as a function call.

To implement ECLIB_VHzProfile16:1. Include ECLIB_VHzProfile16.h. 2. Insert the files S08math.asm, ECLIB_VHzProfile16.c, and S08math.h into the project. 3. Initialize ECLIB_VHZ_CREATE_TABLE.

Implementation Code#include "ECLIB_VHzProfile16.h"

/* Parameters of Volt per Hertz specific to chozen induction motor */#define V_BOOST 10 /* [%] to nominal voltage */#define V_BASE 80 /* [%] to nominal voltage */#define F_BOOST 5 /* [%] to maximal speed */#define F_BASE 80 /* [%] to maximal speed */

vhz_sTable vhzTable = ECLIB_VHZ_CREATE_TABLE(V_BOOST, V_BASE, F_BOOST, F_BASE,0);

signed int output,frequency;

void main(void) { frequency = 1050; output = ECLIB_VHzProfile16(&vhzTable, frequency); }

ECLIB Functions



Figure 3-4. V/Hz Profile

Figure 3-5. V/Hz Profile Performance Example

Performance

Table 3-6. Performance of the ECLIB_VHzProfile16 Function


Data Size (bytes) 9


Max 260

ECLIB Functions



3.3.4 ECLIB_Ramp16

Description

The function increments or decrements the output value by a defined step to bring the actual value closer to the required value.

Availability


Implementation

The ECLIB_Ramp16 function is implemented as a function call. The files ECLIB_Ramp16.h. S08math.asm, ECLIB_Ramp16.c and S08math.h must be inserted into the project.

Implementation Code#include "ECLIB_Ramp16.h"

signed int actValue,reqValue,increment,i,out;

void main(void) { actValue = 1000; reqValue = 500; increment = 100; for(i=0;i<10;i++) { actValue = ECLIB_Ramp16(increment,reqValue,actValue); } }

Performance

Figure 3-6. Ramp Performance Example

ECLIB Functions



Table 3-7. Performance of the ECLIB_Ramp16 Function


Data Size (bytes) 2


Max 188

Documents

Freescale Embedded Software Library S08cache.freescale.com/files/microcontrollers/doc/ref_manual/FSLESLS... · Freescale Embedded Software Library S08 API Reference Manual, Rev. 1