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