NXP Embedded Software Library S08 API - Reference Manual

Freescale Embedded Software Library S08
API Reference Manual
Document Number: FSLESLS08APIRM
Rev. 1
10/2009
How to Reach Us:
Home Page:
www.freescale.com
E-mail:
[email protected]
USA/Europe or Locations Not Listed:
Freescale Semiconductor
Technical Information Center, CH370
1300 N. Alma School Road
Chandler, Arizona 85224
+1-800-521-6274 or +1-480-768-2130
[email protected]
Europe, Middle East, and Africa:
Freescale Halbleiter Deutschland GmbH
Technical Information Center
Schatzbogen 7
81829 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.
Headquarters
ARCO Tower 15F
1-8-1, Shimo-Meguro, Meguro-ku,
Tokyo 153-0064, Japan
0120 191014 or +81 3 5437 9125
[email protected]
Asia/Pacific:
Freescale Semiconductor China Ltd.
Exchange Building 23F
No. 118 Jianguo Road
Chaoyang District
Beijing 100022
China
+86 10 5879 8000
[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.
For Literature Requests Only:
Freescale Semiconductor Literature Distribution Center
1-800-441-2447 or 303-675-2140
Fax: 303-675-2150
[email protected]
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: FSLESLS08APIRM
Rev. 1
10/2009
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.
Revision
Number
Revision
Date
Rev. 1
10/2009
Description of Changes
Launch Release
Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc.
© Freescale Semiconductor, Inc., 2009. All rights reserved.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
iii
Freescale Semiconductor
Chapter 1
Before You Begin
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Library Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reference Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Library Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Listing Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.1 Function Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Types Used in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-1
1-1
1-2
1-2
1-2
1-2
1-2
1-3
1-4
Chapter 2
S08math Functions
2.1
2.2
2.3
Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
S08math Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
S08math Functions Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
2.3.1 add8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
2.3.2 add16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
2.3.3 add32_16_32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
2.3.4 uadd8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
2.3.5 uadd16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
2.3.6 uadd32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
2.3.7 uadd32_64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
2.3.8 sub8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
2.3.9 sub16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
2.3.10 usub8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
2.3.11 usub16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
2.3.12 mul8_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
2.3.13 umul16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
2.3.14 umul32_32_64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
2.3.15 udiv16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
2.3.16 shl16_u8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
2.3.17 shr16_u8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
2.3.18 ushl16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
2.3.19 ushr16_8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
2.3.20 neg8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
2.3.21 neg16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
2.3.22 abs16_8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
2.3.23 fshl8_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
2.3.24 lim32_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
2.3.25 sinLut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
iv
Chapter 3
ECLIB Functions
3.1
3.2
3.3
Library Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ECLIB Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ECLIB Functions Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 ECLIB_3phaseGen16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 ECLIB_ControllerPI16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 ECLIB_VHzProfile16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 ECLIB_Ramp16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-1
3-1
3-2
3-2
3-5
3-7
3-9
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
v
Freescale Semiconductor
Chapter 1 Before You Begin
1.1
Overview
This 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 Features
FSLESLS08 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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
1-1
Before You Begin
1.3
Reference Material
Use 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 Compilers
The 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 Installation
To 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 Integration
To 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 Format
This is the general format of an entry for a function or macro.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
1-2
Freescale Semiconductor
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.
NOTE
The Arguments section is available for a few functions only.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
1-3
Before You Begin
1.8
Data Types Used in Functions
Table 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 long
UINT64[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
1-4
Freescale Semiconductor
Chapter 2 S08math Functions
2.1
Library Integration
To 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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-1
S08math Functions
2.2
S08math Functions Overview
Table 2-1. S08math Functions Summary
Performance
Function
Code
size
(byte)
Execution
(cycle)
Parameter
Return (Out)
Description
min max
add8
16
20
22
x
y
in
in
signed char
signed char
signed char
8-bit signed addition
with overflow control
and saturation
add16
26
32
35
x
y
in
in
signed int
signed int
signed int
16-bit signed addition
with overflow control
and saturation
add32_16_32
78
79
86
x
y
in
in
signed long
signed int
signed long
32-bit signed addition,
accumulation
uadd8
10
16
18
x
y
in
in
unsigned char
unsigned char
unsigned char
8-bit unsigned addition
with overflow control
and saturation
uadd16
19
32
35
x
y
in
in
unsigned int
unsigned int
unsigned int
16-bit unsigned
addition with overflow
control and saturation
uadd32
45
59
76
x
y
in
in
unsigned long
unsigned long
unsigned long
32-bit unsigned
addition with overflow
control and saturation
uadd32_64
55
89
100
x
y
sub8
16
21
22
x
y
in
in
sub16
26
35
38
x
y
usub8
9
17
18
usub16
20
28
mul8_8_16
28
45
in
unsigned long
in/out
UINT64[2]
void
Addition of unsigned
32-bit number with
unsigned 64-bit number
signed char
signed char
signed char
8-bit signed subtraction
with overflow control
and saturation
in
in
signed int
signed int
signed int
16-bit signed
subtraction with
overflow control and
saturation
x
y
in
in
unsigned char
unsigned char
unsigned char
8-bit unsigned
subtraction with
overflow control and
saturation
32
x
y
in
in
unsigned int
unsigned int
unsigned int
16-bit unsigned
subtraction with
overflow control and
saturation
53
x
y
in
in
signed char
signed char
signed int
8-bit signed
multiplication with
16-bit result
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-2
Freescale Semiconductor
S08math Functions
Table 2-1. (continued)S08math Functions Summary
Performance
Function
Code
size
(byte)
Execution
(cycle)
Parameter
Return (Out)
Description
16x8 unsigned
fractional multiplication
with 16-bit result
min max
umul16_8_16
27
45
53
x
y
in
in
unsigned int
unsigned char
unsigned int
umul32_32_64
420
635
667
x
y
in
in
unsigned long
unsigned long
void
udiv16_8_16
15
44
54
x
y
in
in
unsigned int
unsigned char
unsigned int
shl16_u8_16
24
55
257
x
shift
in
in
signed int
unsigned char
signed int
16-bit signed shift left
with overflow control
and saturation
shr16_u8_16
17
63
287
7
x
shift
in
in
signed char
unsigned char
signed int
16-bit signed shift right
ushl16_8_16
24
30
226
x
shift
in
in
unsigned int
unsigned char
unsigned int
16-bit unsigned shift left
with overflow control
and saturation
ushr16_8_16
17
30
284
9
x
shift
in
in
unsigned char
unsigned 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
phas
e
amp
in
in
unsigned char
unsigned char
signed int
Limitation of signed
long number in signed
integer range
sinLut
25
34
39
x
y
in
in
signed char
signed char
signed char
32-bit unsigned
multiplication with
64-bit result
Unsigned fractional
division 16-bit value by
8-bit with 16-bit result.
Look-up table sine
computation
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-3
S08math Functions
2.3
2.3.1
S08math Functions Description
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
Min
79
Max
86
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-4
Freescale Semiconductor
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
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
Min
32
Max
35
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-5
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
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
Min
32
Max
35
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-6
Freescale Semiconductor
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
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
Min
16
Max
18
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-7
S08math Functions
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
Min
32
Max
35
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-8
Freescale Semiconductor
S08math Functions
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
Min
32
Max
35
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-9
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
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
Table 2-8. Performance of the uadd32_64 Function
Code Size (bytes)
55
Data Size (bytes)
0
Min
89
Max
100
Execution Clock (cycles)
An application of this special type of function is the summation of enormous numbers for further
computation (integration, averaging).
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-10
Freescale Semiconductor
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
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
Min
21
Max
22
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-11
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
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
Min
35
Max
38
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-12
Freescale Semiconductor
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
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
Min
17
Max
18
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-13
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
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
Min
28
Max
32
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-14
Freescale Semiconductor
S08math Functions
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
Min
45
Max
53
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-15
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
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
Table 2-14. Performance of the umul16_8_16 Function
Code Size (bytes)
28
Data Size (bytes)
0
Min
45
Max
53
Execution Clock (cycles)
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.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-16
Freescale Semiconductor
S08math Functions
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
Min
635
Max
667
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-17
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
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
Min
44
Max
54
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-18
Freescale Semiconductor
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
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
Min
55
Max
257
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-19
S08math Functions
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
Min
63
Max
2877
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-20
Freescale Semiconductor
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
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
Min
30
Max
226
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-21
S08math Functions
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
Min
30
Max
2849
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-22
Freescale Semiconductor
S08math Functions
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
Min
25
Max
29
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-23
S08math Functions
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
Min
22
Max
31
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-24
Freescale Semiconductor
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
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
Min
33
Max
35
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-25
S08math Functions
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
Min
29
Max
29
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-26
Freescale Semiconductor
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
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
Min
57
Max
72
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-27
S08math Functions
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-28
Freescale Semiconductor
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
Input Parameter
Size
Meaning
amplitude
0...255
0...100%
phase
0...255
0...359°
Performance
Table 2-27. Performance of the sinLut Function
Code Size (bytes)
25
Data Size (bytes)
128
Min
34
Max
39
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
2-29
S08math Functions
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
2-30
Freescale Semiconductor
Chapter 3 ECLIB Functions
3.1
Library Integration
The 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
amplitude
actualPhase
phaseA
phaseB
phaseC
in
in
out
out
out
unsigned char
unsigned char
unsigned int
unsigned int
unsigned int
structure
Calculates the 3-phase
sine wave generator.
ECLIB_ControllerPI16
error
piParams
in
in/out
signed int
structure
signed int
Calculates the standard
16-bit PI
(Proportional-Integral)
controller with
limitation.
ECLIB_VHzProfile16
vhzTable
frequency
in
in
structure
signed int
signed int
Calculates Volt per
Hertz profile.
ECLIB_Ramp16
increment
reqValue
actValue
in
in
out
signed int
signed int
signed 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.
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
3-1
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;
}
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-2
Freescale Semiconductor
ECLIB Functions
Arguments
Table 3-2. Function Parameters Description
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%
Performance
Table 3-3. Performance of the ECLIB_3phaseGen16 function
Code Size (bytes)
106
Data Size (bytes)
128
Min
171
Max
215
Execution Clock (cycles)
Figure 3-1. Output Waveforms for 100% Amplitude
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
3-3
ECLIB Functions
Figure 3-2. Output Waveforms for 50% Amplitude
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-4
Freescale Semiconductor
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
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);
}
Arguments
Table 3-4. Function Parameters Description
Parameter
Size
Meaning
pPIparams.propGain
unsigned char
0...100%
signed char
positive value - shift left
negative value - shift right
pPIparams.propGainShift
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
3-5
ECLIB Functions
Parameter
Size
Meaning
pPIparams.intGain
unsigned char
0...100%
signed 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
pPIparams.intGainShift
Performance
Table 3-5. Performance of the ECLIB_ControllerPI16 Function
Code Size (bytes)
352
Data Size (bytes)
34
Min
607
Max
3474
Execution Clock (cycles)
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-6
Freescale Semiconductor
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
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
#define V_BOOST 10 /*
#define V_BASE 80 /*
#define F_BOOST 5 /*
#define F_BASE 80 /*
per
[%]
[%]
[%]
[%]
Hertz specific to chozen induction motor */
to nominal voltage */
to nominal voltage */
to maximal speed */
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);
}
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
3-7
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
Code Size (bytes)
80
Data Size (bytes)
9
Min
103
Max
260
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-8
Freescale Semiconductor
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
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
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
Freescale Semiconductor
3-9
ECLIB Functions
Table 3-7. Performance of the ECLIB_Ramp16 Function
Code Size (bytes)
45
Data Size (bytes)
2
Min
113
Max
188
Execution Clock (cycles)
Freescale Embedded Software Library S08 API Reference Manual, Rev. 1
3-10
Freescale Semiconductor