Upload
lydien
View
242
Download
3
Embed Size (px)
Citation preview
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
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 Embedded Software Library S08 API Reference Manual, Rev. 1
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 1-3
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
1-4 Freescale Semiconductor
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.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-1
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-2 Freescale Semiconductor
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 charsigned char
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 charunsigned char
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 charsigned char
signed int 8-bit signed multiplication with 16-bit result
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-3
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 intunsigned char
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 intunsigned char
unsigned int 16-bit unsigned shift left with overflow control and saturation
ushr16_8_16 17 30 2849
xshift
inin
unsigned charunsigned char
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
unsigned charunsigned char
signed int Limitation of signed long number in signed integer range
sinLut 25 34 39 xy
inin
signed charsigned char
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-4 Freescale Semiconductor
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-5
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The add16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 26
Data Size (bytes) 0
Execution Clock (cycles)Min 32
Max 35
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-6 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
Implementation
The add32_16_32 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 26
Data Size (bytes) 0
Execution Clock (cycles)Min 32
Max 35
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-7
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The uadd8 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 10
Data Size (bytes) 0
Execution Clock (cycles)Min 16
Max 18
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-8 Freescale Semiconductor
2.3.5 uadd16
Description
The function performs the unsigned 16-bit addition with overflow control and saturation. The 16-bit result is set at +65534 on overflow.
Availability
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The uadd16 function is implemented as a function call.
Implementation Code#include "S08math.h"
unsigned int x,y,z;
void main(void) { x = 50000; y = 15000; z = uadd16(x,y);}
Performance
Table 2-6. Performance of the uadd16 Function
Code Size (bytes) 19
Data Size (bytes) 0
Execution Clock (cycles)Min 32
Max 35
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-9
2.3.6 uadd32
Description
The function performs the unsigned 32-bit addition with overflow control and saturation. The 32-bit result is set at +4294967295 on overflow.
Availability
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The uadd32 function is implemented as a function call.
Implementation Code#include "S08math.h"
unsigned long x,y,z;
void main(void) { x = 50000; y = 150000; z = uadd32(x,y);}
Performance
Table 2-7. Performance of the uadd32 Function
Code Size (bytes) 19
Data Size (bytes) 0
Execution Clock (cycles)Min 32
Max 35
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-10 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
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).
Implementation Code#include "S08math.h"
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
Code Size (bytes) 55
Data Size (bytes) 0
Execution Clock (cycles)Min 89
Max 100
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-11
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The sub8 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 16
Data Size (bytes) 0
Execution Clock (cycles)Min 21
Max 22
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-12 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The sub16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 26
Data Size (bytes) 0
Execution Clock (cycles)Min 35
Max 38
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-13
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The usub8 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Execution Clock (cycles)Min 17
Max 18
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-14 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated.
Implementation
The usub16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 20
Data Size (bytes) 0
Execution Clock (cycles)Min 28
Max 32
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-15
2.3.12 mul8_8_16
Description
The function performs the signed 8-bit multiplication with a 16-bit result.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The mul8_8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 28
Data Size (bytes) 0
Execution Clock (cycles)Min 45
Max 53
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-16 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
Implementation
The umul16_8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 28
Data Size (bytes) 0
Execution Clock (cycles)Min 45
Max 53
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-17
2.3.14 umul32_32_64
Description
The function performs the unsigned 32-bit multiplication with a 64-bit result.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The umul32_32_64 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 420
Data Size (bytes) 0
Execution Clock (cycles)Min 635
Max 667
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-18 Freescale Semiconductor
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
This library module is available in the C-callable interface assembly format.
Special Issues
The result is saturated. 2
Implementation
The udiv16_8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 15
Data Size (bytes) 0
Execution Clock (cycles)Min 44
Max 54
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-19
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
This library module is available in the C-callable interface assembly format.
Implementation
The shl16_u8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 54
Data Size (bytes) 0
Execution Clock (cycles)Min 55
Max 257
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-20 Freescale Semiconductor
2.3.17 shr16_u8_16
Description
The function performs the shift right of a signed 16-bit input variable.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The shr16_u8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 40
Data Size (bytes) 0
Execution Clock (cycles)Min 63
Max 2877
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-21
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
This library module is available in the C-callable interface assembly format.
Implementation
The ushl16_8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 24
Data Size (bytes) 0
Execution Clock (cycles)Min 30
Max 226
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-22 Freescale Semiconductor
2.3.19 ushr16_8_16
Description
The function performs the shift right of an unsigned 16-bit input variable.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The ushr16_8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 17
Data Size (bytes) 0
Execution Clock (cycles)Min 30
Max 2849
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-23
2.3.20 neg8
Description
The function performs the negation of an 8-bit input variable.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The neg8 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Execution Clock (cycles)Min 25
Max 29
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-24 Freescale Semiconductor
2.3.21 neg16
Description
The function performs the negation of a 16-bit input variable.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The neg16 function is implemented as a function call.
Implementation Code#include "S08math.h"
signed int x,z;
void main(void) { x = 5000; z = neg16(x);}
Performance
Table 2-22. Performance of the neg16 Function
Code Size (bytes) 28
Data Size (bytes) 0
Execution Clock (cycles)Min 22
Max 31
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-25
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
This library module is available in the C-callable interface assembly format.
Implementation
The abs16_8 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 11
Data Size (bytes) 0
Execution Clock (cycles)Min 33
Max 35
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-26 Freescale Semiconductor
2.3.23 fshl8_16
Description
The function performs a fast instant 7-bits shift left.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The fshl8_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Execution Clock (cycles)Min 29
Max 29
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-27
2.3.24 lim32_16
Description
The function performs limitation of an input signed 32-bit variable in the signed 16-bit range.
Availability
This library module is available in the C-callable interface assembly format.
Implementation
The lim32_16 function is implemented as a function call.
Implementation Code#include "S08math.h"
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
Code Size (bytes) 49
Data Size (bytes) 0
Execution Clock (cycles)Min 57
Max 72
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-28 Freescale Semiconductor
2.3.25 sinLut
Description
The function performs the look-up table sine calculation.
Availability
This library module is available in the C-callable interface assembly format.
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 2-29
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
Code Size (bytes) 25
Data Size (bytes) 128
Execution Clock (cycles)Min 34
Max 39
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-30 Freescale Semiconductor
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 3-1
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-2 Freescale Semiconductor
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 3-3
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
Code Size (bytes) 106
Data Size (bytes) 128
Execution Clock (cycles)Min 171
Max 215
ECLIB Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-4 Freescale Semiconductor
Figure 3-2. Output Waveforms for 50% Amplitude
ECLIB Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 3-5
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
This library module is available in the C-callable interface format.
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
Parameter Size Meaning
pPIparams.propGain unsigned char 0...100%
pPIparams.propGainShiftsigned char positive value - shift left
negative value - shift right
ECLIB Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-6 Freescale Semiconductor
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
Code Size (bytes) 352
Data Size (bytes) 34
Execution Clock (cycles)Min 607
Max 3474
Parameter Size Meaning
ECLIB Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 3-7
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
This library module is available in the C-callable interface format.
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-8 Freescale Semiconductor
Figure 3-4. V/Hz Profile
Figure 3-5. V/Hz Profile Performance Example
Performance
Table 3-6. Performance of the ECLIB_VHzProfile16 Function
Code Size (bytes) 80
Data Size (bytes) 9
Execution Clock (cycles)Min 103
Max 260
ECLIB Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor 3-9
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
This library module is available in the C-callable interface format.
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-10 Freescale Semiconductor
Table 3-7. Performance of the ECLIB_Ramp16 Function
Code Size (bytes) 45
Data Size (bytes) 2
Execution Clock (cycles)Min 113
Max 188