USE IN LIFE SUPPORT DEVICES OR SYSTEMS MUST BE EXPRESSLY AUTHORIZED. STMicroelectronics PRODUCTS ARE NOT AUTHORIZED FOR USE AS CRITICAL COMPONENTS IN LIFE SUPPORT DEVICES OR SYSTEMS WITHOUT THE EXPRESS WRITTEN APPROVAL OF STMicroelectronics. As used herein: 1.Life support devices or systems are those which (a) are intended for surgical implant into the body, or (b) support or sustain life, and whose failure to perform, when properly used in accordance with instructions for use provided with the product, can be reasonably expected to result in significant injury to the user. 1 2. A critical component is any component of a life support device or system whose failure to perform can reasonably be expected to cause the failure of the life support device or system, or to affect its safety or effectiveness.

USER MANUAL
ST7 FAMILY ST7 SOFTWARE LIBRARY
1 INTRODUCTION
This document describes the features, the files structure, examples, module drivers and guidelines for using the ST7 software library package. 1.1 ABBREVIATIONS USED · SCI · ADC · SPI · I2C · CAN · WDG · EEPROM · ITC · I/O · PWM · ART · TBU · TIMER · TIMER8 · LT · LART · STVD7 · MCD 1.2 NAMING CONVENTIONS Periph. All names starting with Periph are referring to the name of the peripheral. Serial Communication Interface Analog to Digital Converter Serial peripheral Interface Inter Integrated Circuit Controller Area Network Watchdog Electrically Erasable Prog. Read Only Memory Interrupt Controller Input/Output Ports Pulse Width Modulation Auto Reload Timer Time Base Unit 16-bit Timer 8-bit Timer Lite Timer Lite Auto Reload Timer ST Visual Debug 7 Microcontroller Division

Rev. 4.0
November 2005

Table of Contents
1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 ABBREVIATIONS USED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 NAMING CONVENTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1 FUNCTIONAL SCOPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2 FEATURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3 GETTING STARTED WITH TOOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1 SOFTWARE TOOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2 HARDWARE TOOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3 TECHNICAL LITERATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.4 HOW TO INSTALL THE LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4 LIBRARY STRUCTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1 ST7_LIBX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2 ST7LIB_CONFIG.H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2.1 4.2.2 4.3.1 4.3.2 User part of the ST7lib_config.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Non-User part of the ST7lib_config.h . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Peripherals directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Periph directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.3.2.1 C directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.3 PERIPHERALS LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.4 DEVICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.5 DOCUMENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.6 DEMO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5 EXAMPLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1 SOURCES FOLDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.2 WORKSPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 5 . 15 3. 5.2.1 STVD7_2x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4/235

1

Table of Contents
5.2.2 5.2.3 STVD7_3x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 winIDEA (only for ST72F561 and CAN peripheral) . . . . . . . . . . . . . . . . 15

6 HOW TO USE THE LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.1 STANDARD PROCEDURE FOR ALL PERIPHERALS . . . . . . . . . . . . . . . . . . . 16 6.2 USING THE COMMUNICATION PERIPHERALS LIBRARY . . . . . . . . . . . . . . 17 6.2.1 6.2.2 6.2.3 6.2.4 SCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 I2C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 CAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 6.2.4.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6.2.4.2 DATA STRUCTURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6.2.4.3 DATA TYPES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.2.4.4 MEMORY USAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.2.4.5 PARAMETER CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . 23 6.2.4.6 Tx & Rx BUFFER USAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.2.4.7 IMPLEMENTATION HINTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.3 OTHER PERIPHERALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6.3.1 6.3.2 TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.4 MEMORY MODELS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6.5 PORTING APPLICATIONS FROM LIBRARY VERSION 1.0 . . . . . . . . . . . . . . 26 7 PRESENTATION OF LIBRARY FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 7.1 LIBRARY REFERENCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 8 RELEASE INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 8.1 PERIPHERALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 8.2 DEVICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 9 FUNCTION DESCRIPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 9.1 GENERAL PURPOSE PERIPHERALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 9.1.1 9.1.2 9.1.3 9.1.4 9.1.5 ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 SCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 3. I2C MASTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 5 . 81 I2C SLAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

5/235

Table of Contents
9.1.6 9.1.7 9.1.8 9.1.9 9.1.1 0 9.1.1 1 9.1.1 2 9.1.1 3 9.1.1 4 9.1.15 9.1.1 6 9.2.1 16-bit TIMER (TIMER) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 8-bit TIMER (TIMER8) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 LITE TIMER (LT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 PWMART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 LITE AUTO-RELOAD TIMER (LART) . . . . . . . . . . . . . . . . . . . . . . . . . 171 TBU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 WDG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 ITC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 MCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 EEPROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

9.2 APPLICATION SPECIFIC PERIPHERALS . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 CAN LIBRARY FUNCTION LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 9.2.1.1 Initialization-Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 9.2.1.2 Transmit-Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 9.2.1.3 Sleep/Wakeup Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 9.2.1.4 Status Information Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 9.2.1.5 Transmit/Receive Task Services . . . . . . . . . . . . . . . . . . . . . . . . 231 9.2.1.6 Interrupt Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

10 APPENDIX A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 10.1SUPPORTED DEVICES AND THEIR PERIPHERALS . . . . . . . . . . . . . . . . . . 233 11 REVISION HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

235

6/235

Overview

2 OVERVIEW
2.1 FUNCTIONAL SCOPE ST7 library is a software package consisting of device drivers for all standard ST7 peripherals. Each device driver has a set of functions covering the functionality of the peripheral. The source code, developed in `C' is fully documented and thoroughly tested. This library has been developed to make it easy for you to develop ST7 applications. A basic knowledge of C programming is required. With ST7 library, you can use any ST7 device in your application without having to study each peripheral specification in-depth. As a result, using this library can save you a lot of coding time and save part of the cost of developing and integrating your application. 2.2 FEATURES NEW: Supports new devices ST72325 and ST7232A NEW: Provided workspace for both STVD7 version 3.x and 2.x The ST7 library package consists of device driver library files, the configuration and setup files. With each peripheral, application example code is provided. This is an application tailored to a specific ST7 device, which uses the library functions to drive the peripheral. You can use it without modification in an ST development kit. A detailed function reference is provided for each peripheral The functional behaviour and input/output parameters of each function are described in detail in the user manual The functions are coded in 'C' and are compatible with Metrowerks & Cosmic compilers The ST7 library is MISRA compliant Registry Key is added to provide information on installation path and version

7/235

Getting Started with Tools

3 GETTING STARTED WITH TOOLS
3.1 SOFTWARE TOOLS The library functions have been debugged with the ST7 software toolset. The ST7 software toolset can be found on the MCU CD-ROM or can be downloaded from the ST website: http://www.st.com/mcu The following versions of the C compilers are used: METROWERKS C toolchain version 4.2.5 COSMIC C toolchain version 4.4d A valid license has to be purchased for Metrowerks and Cosmic compilers. Free versions with code limitations may also be available, check the websites of the two providers for further info rmation.
Note: Since Metrowerks was previously known as Hiware, both C compilers are compatible.

3.2 HARDWARE TOOLS Hardware tools are not required for using the library, you can use the STVD7 simulator if it supports the target device (check with the latest device documentation). However you can use the following Hardware tools for development support: ICD based debugging tools (like InDart from Softec or R-Link ST from Raisonance) ST Emulators (EMU or DVP) ST7232x - SK/ RAIS (Starter Kit by Raisonance) ST evaluation boards / starter kits (for example ST7232x-EVAL) ST7-STICK - ST in-circuit communication kits ICC socket boards - these complement any tool that has ICC programming capabilities (like ST7-STICK, InDART, R-Link, DVP, EMU, etc.) Third party emulators (from Hitex or iSYSTEM) Engineering Programming Board (EPB) or Gang Programmer 3.3 TECHNICAL LITERATURE As well as reading the ST7 device datasheet, you should also read the following documents before using the library. All the documents and the device datasheets are available on the ST website and on the MCU CD ROM. ST7 Software library user manual Application note: AN978: Key features of the STVD7 ST7 Visual debug package Application note: AN989: Getting started with the ST7 Hiware C Toolchain Application note: AN983: Key features of the Cosmic ST7 C- Compiler package Application note: AN1064: Writing Optimized Hiware C Language for ST7 Application note: AN1938: Visual Develop for ST7 Cosmic C Toolset Users Application note: AN1939: Visual Develop for ST7 Metrowerks C Toolset Users

8/235

1

Getting Started with Tools

3.4 HOW TO INSTALL THE LIBRARY The library is supplied in a zip package. Extraction of this zip file will give the setup file ST7LibxSetup.exe, where x represents the latest numeric version of the library. Click on the setup file to install the library on the host system.

9/235

Library Structure

4 LIBRARY STRUCTURE
4.1 ST7_LIBX Location: \Root directory Description: The ST7_libx (where x represents the latest numeric version of the library) is installed by default in the root directory. It is comprised of five main components: the ST7library configuration file, the Peripherals (Device driver) library folder, the devices configuration files folder, documentation on the package and the demo folder. The location of these components is described in this section and shown in the figure given below. Note: The Example directory is shown in Figure 2 on page 14. Figure 1. Main Directory structure

ST7_LIB x

ST7lib_config.h

Peripherals

Devices

Documentation

Demo

Peri p h 1 Periph 2

Device 1

Device n Periph14 device_reg.h device_reg.c device_periph.h Metrowerks Example periph.c periph.h periph_hr.h Cosmic

C Folder

4.2 ST7LIB_CONFIG.H Location: ST7_libx\ST7lib_config.h Description: ST7lib_config.h is the entry point for the user. You have to include this file in your application (main.c). This file is used to define specific labels for example, to define the mode of transmission of communication peripherals, cpu frequency, etc.

10/235

Library Structure

St7lib_config.h is divided into two major sections: 4.2.1 User part of the ST7lib_config.h You can customize this portion to your application requirement You can define your own labels and macros here You can change the CPU clock value (default is 8MHz) For the ST72F264 device you can select whether to use Port C as ei0 or ei1 The target ST7 device file (st72xxx_periph.h) has to be included in this file Note: An error message "No Valid ST7 MCU Configuration" will be generated by the compiler if no device file has been included. 4.2.2 Non-User part of the ST7lib_config.h This part contains the labels for METROWERKS and COSMIC compilers. It contains the compiler definitions as follows:
#if (defined __HIWARE__ | defined __MWERKS__ ) #define _HIWARE_ #else #ifdef __CSMC__ #define _COSMIC_ #else #error "Unsupported Compiler!" #endif #endif

/* Compiler defines not found */

The labels __MWERKS__ (__HIWARE__) and __CSMC__ are automatically set by the Metrowerks and cosmic compilers respectively. If none of these two compilers are selected then an error message "Unsupported Compiler!" appears on the debugger window. Macros definitions in ST7lib_config.h: ST7lib_Config.h file also contains a list of macros. They are as follows. 1. EnableInterrupts: You can use this macro to reset the interrupt mask, this macro is equivalent to the RIM instruction in assembly. 2. Nop: No operation. This is equivalent to the nop instruction in assembly 3. DisableInterrupts: You can use this macro to set the interrupt mask, this macro is equivalent to the SIM instruction in assembly. 4. WaitforInterrupt: This is equivalent to the "wfi" instruction in assembly. 4.3 PERIPHERALS LIBRARY 4.3.1 Peripherals directory Lo cation: ST7_libx\Peripherals Description: This directory contains subdirectories by the name of the peripheral. Subdirectory names: ADC, EEPROM, I2C, I2CSlave, IO, ITC, LART, LT, MCC, PWMART, SCI, SPI, TBU, TIMER, TIMER8, WDG, CAN. 4.3.2 Periph directory Location: ST7_libx\Peripherals\Periph\sources

11/235

Library Structure

Description: Each subdirectory contains a `C' sub folder which contains peripheral library files. 4.3.2.1 C directory Location: ST7_libx\Peripherals\Periph\sources\C Description: Each subdirectory contains the source files, header files and an example folder showing the usage of the functions. Files: Periph.c, Periph.h, Periph_hr.h Periph.c Inclusion of periph_hr.h, periph.h, ST7lib_config.h. It contains the Peripheral functions with some conditional compilation options. Periph.h: This contains the (typedef enum) parameters for each peripheral, prototypes of functions defined in Peripheral.c and definition of Peripheral constant definitions. Periph_hr.h This file contains the bit mapping of the hardware registers used for the peripherals. 4.4 DEVICES Lo cation: ST7_LIBx\Devices D es c r i p t i o n : 1. Contains the files which define all registers for each device and includes the file which is used to select peripherals for the application. This register file is included in the ST7lib_config.h. T h e folder ST7_LIBx\Devices\ST7xx contains st7xx_reg.h, st7xx_reg.c and st7xx_periph.h files. s t 7 x x _ r e g . h : This file contains a declaration of the register variables of st7xx for Metrowerks and definitions of the register variables for the Cosmic compiler. st7xx_reg.c: This file contains definitions of the register variables of st7xx device. st7xx_periph.h: This file is used to select which peripherals of st7xx device are used in the application. 2. Contains the generic configuration files both Metrowerks and Cosmic compilers. Metrowerks: Contains the mapping file (ST72xxx.prm) for all the hardware registers in device, Make file (ST72xxx.mak) to build the application and the default.env which defines all the useful paths and options for the application. COSMIC: make file to build the application (ST72xxx.mak), link file (ST72xxx.lkf) used to link the device and the interrupt mapping file (vector_xxx.c) for the target device. Notes: 1. This software covers 13 main devices and their subsets. You have to include the file from the main device section in order to support the related subsets. 2. The register files in the ST7 library are different from those provided with the STVD7 ver 3.x. Take care to include the correct one.

12/235

Library Structure

Table 1. Supported devices
Main device ST72F62 ST72F63B ST72F65 ST72F521 ST72325 ST7232A ST7FLITE0 ST7FLITE1 ST7FLITE2 ST7FLITE3 ST72F264 ST72F561 ST7SUPER LITE Subsets ST72F621, ST72F622, ST72F623, ST72F611 ST72F63BK1, ST72F63BK2, ST72F63BK3 ST72F65 ST72F521, ST72F321,ST72F324 ST72F325(C/J/K)4, ST72F325(AR/C/J/K)6/7/9 ST72F32AK2 ST7FLITE05, ST7FLITE09 ST7FLITE10, ST7FLITE15, ST7FLITE19, ST7FLITE1B ST7FLITE20, ST7FLITE25, ST7FLITE29 ST7FLITE3 ST72F260G1, ST72F262G1, ST72F262G2, ST72F264G1, ST72F264G2 ST72F561(R/J/K)9, ST72F561(R/J/K)6 ST7FLITES2, ST7FLITES5

4.5 DOCUMENTATION Lo cation: ST7_LIBx\Documentation Description: This directory contains the global user manual describing each peripheral library and its use in detail. Files: user manual.pdf 4.6 DEMO Location: ST7_LIBx\DEMO Description: This directory contains an application program which demonstrates the use of the ST7LIB on the devices ST72F521, ST72F62, ST7FLITE0, ST7FLITE2, ST7SUPERLITE, ST72F561 and ST72325. The program uses all the peripheral libraries together for a particular application. The purpose of the demo is to help to develop an application using the software library.

13/235

Example

5 EXAMPLE
Location: ST7_LIBx\Peripherals\Periph\sources\C\Example Description: Contains the example application code for each peripheral individually. The code has been developed using the peripheral library functions exercises the functionality of that peripheral. The configuration and workspace has been provided for users of both STVD7 ver2.x and 3.x. The example has been compiled and tested using both Metrowerks and Cosmic compilers and configuration files are provided. Subdirectories: Sources, workspace Figure 2. Example directory structure

Example

Sources main.c st7lib_config.h st72xx_periph.h

workspace

STVD7_2x

STVD7_3x

Config

periph_mwerks.wsp periph_csmc.wsp Metrowerks Cosmic

Object

Cosmic

M e trowerks Metrowerks

periph_mwerks.stw periph_mweks.stp interrupt_vector.c vector.c periph_csmc.stw periph_csmc.stp

st72xxx.mak st72xxx.lkf vector_xxx.c

st72xxx.mak st72xxx.prm default.env

periph . map periph.elf periph.o main.o periph_hr.0 periph.st7 vector_xxx.o periph.s19

periph . map periph.abs periph.o main.o periph_hr.0 periph.s19

5.1 SOURCES FOLDER Description: Contains the ST7lib_config.h, the main application file and the peripheral source files needed to run the application

14/235

Example

5.2 WORKSPACE This folder contains configuration and workspace files for both STVD7 ver2.x and 3.x as per the directory structure shown in figure 2. Note: 1. For ST72F561 demo and CAN peripheral, winIDEA workspace is also available. 2. For ST72325 and ST7232A demo STVD7_3X workspace is only available. 5.2.1 STVD7_2x This folder contains relevant configuration files for ST7 Visual Debug ver 2.x. Subdirectories: Config, Object Config Folder: Contains the configuration files for both Metrowerks and Cosmic compilers. metrowerks: Contains the mapping file (ST72xxx.prm) for all the hardware registers in the device, the Make file (ST72xxx.mak) for building the application and the default.env file which defines all the useful paths names and options for the application. COSMIC: Contains the make file for building the application (ST72xxx.mak), the link file (ST72xxx.lkf) used to link the device and the interrupt mapping file (vector_xxx.c) for the target device. Object Folder: These folders are used for temporary storage of object and executable files generated by the compiler in respective directories - metrowerks and cosmic. 5.2.2 STVD7_3x This folder contains relevant Cosmic and Metrowerks workspace for ST7 Visual Debug ver 3.X, as the configuration files are automatically generated. 5.2.3 winIDEA (only for ST72F561 and CAN peripheral) This folder contains relevant configuration files for winIDEA. Subdirectories: Config, Object For details related to Subdirectories refer to Section 5.2.1

15/235

How to use the library

6 HOW TO USE THE LIBRARY
The next section gives the standard procedure to be followed for all the peripherals. Some specific instructions are given in the section 7.2 which have to be followed if you use the communication peripherals. 6.1 STANDARD PROCEDURE FOR ALL PERIPHERALS Note: This section is only applicable if you are using STVD7 v2.x. 1. Install ST7_LIBx in one directory as per the installation procedure. 2. When starting for the first time, copy the structure from the demo directory. 3. Choose the target device and copy the configuration files (for Metrowerks or Cosmic) from the devices directory into the user configuration directory. 4. Update the useful paths and link the chosen peripherals files. The source path will refer to the directory where ST7_LIBx is installed. For example, assuming that you have installed ST7_LIBx in D:\ a) The following paths will be updated for Metrowerks in the Default.env: ST7LIB_PT: Change this path to installation of library TOOL_PT: Change this path to Metrowerks toolchain path Depending on the peripherals required for the application update the object list in *.prm and *.mak files. b) The following paths will be updated for Cosmic in *.mak file Update the source path PATHC: Change this path to cosmic toolchain installation path LIB_PT: Change this path to library installation path SRx_PT = $(LIB_PT)\peripherals\periph\C where x is the no. of source path for each peripheral where periph is the name of the peripheral used in the application Update the include path CFLAGS = +mods +debug -co $(OBJ_PT) -i $(SRx_PT) where x is the no. of source path for each peripheral (give the path of all the peripherals present in the particular device) Update the source list SRC_LIST = $(OBJ_PT)\..\..\source\main.c $(SRx_PT) where x is the no. of peripheral used 5. Modify ST7lib_config.h file to include the target device, CPU frequency and the communication mode if any of the communication peripherals is used. 6. Include ST7lib_config.h in main.c

16/235

How to use the library

7. Write the application program using the library functions given in the user manual for each peripheral and compile. Caution: Only the ST7lib_config.h and the files contained in the configuration subdirectory of the examples folder are user-modifiable, the rest of the source files are write protected. Changing peripheral source files and header files may adversely affect the library operations and this will be complicated to update when there are new library releases. 6.2 USING THE COMMUNICATION PERIPHERALS LIBRARY 6.2.1 SCI This part of the user manual contains the detailed description of all the functions for the SCI. An example `C' program has been given at the end. You can select either of the two Transmission/Reception modes of SCI implemented inside the library. For selecting any of the possible modes described below you need to select the corresponding #define statement inside the ST7lib_Config.h file Polling: With this mechanism the data can be transmitted or received by polling the status of the corresponding flag. Here both the single as well as continuous Transmission/Reception is possible. In continuous Transmission/Reception, control will be inside the function until all the requested data is Transmitted/Received and hence the application software has the risk of losing control if there is a breakdown in communication (the SCI mode is disabled). To avoid this risk, you can use the single byte transmission with some time out protection inside this mechanism. This mechanism can only be used with the SCI in half duplex mode. To use this mode you must have selected the following # define labels inside the ST7lib_config.h file: SCI_POLLIN G_TX -- For Transmission mode SCI_POLLIN G_R X -- For Reception mode For SCI2 in ST72F561 device the labels are: SCI2_ POLLIN G_ TX -- For Transmission mode SCI2_POLLING_RX -- For Reception mode Interrupt driven without communication buffer: With this method data can be Transmitted/Received either in single or continuous mode using interrupts. In continuous mode the user data is directly being read/written from/to the addresses passed by the user. After each byte of data transfer an interrupt is acknowledged and the control goes to the interrupt subroutine. The main advantage of using interrupts rather than polling is that control does not stay in the function till the last data is Transmitted/Received and hence the SCI can be used in full duplex mode. Here, you should take care not to read/write the user buffer until the Transmission/Reception is complete. To use this mode you must select the following # define labels in the ST7lib_config.h file: SCI_ITDRV_WITHOUTBUF_TX -- For Transmission SCI_ITDRV_WITHOUTBUF_RX -- For Reception For SCI2 in ST72F561 device the labels are: SCI2_ITDRV_WITHOUTBUF_TX -- For Transmission on SCI2 SCI2_ITDRV_WITHOUTBUF_RX -- For Reception on SCI2
17/235

How to use the library

6.2.2 SPI SPI: This part of the user manual contains the detailed description of all the functions for the SPI. An example C program has been given at the end. The SPI can be used as Single master (multiple slaves) and multi master systems in full duplex mode. This can be configured by using parallel port pins to control the SS pin by software. The transfer of master or slave control can be implemented using a handshake method through the I/O ports or by an exchange of code messages through the serial peripheral interface system. In order to respect the SPI protocol, you must define the configuration setting SPI_SLAVE_CONFIG in ST7lib_config.h file as shown below, in order to be able to transmit data in software slave mode. #define SPI_SLAVE_CONFIG To select any of the possible communication modes described below you need to select the corresponding #define statement inside the ST7lib_config.h file. These modes are applicable for all communication peripherals (SPI, SCI and I2C). Polling: With this mechanism the data can be transmitted or received by polling the status of the corresponding flag. Both single and continuous Transmission/Reception is possible. In the case of continuous Transmission/Reception the function keeps control until all the requested data is Transmitted/Received and hence the application software has the risk of losing control if there is a breakdown in communication (the SCI mode is disabled). To avoid the risk, you can use the single byte transmission with some timeout protection inside this mechanism. This mechanism can only be used with the SPI in half duplex mode. To use this mode, you must have selected the following # define labels inside the ST7lib_config.h file: SPI_POLLING_TX -- For Transmission mode SPI_POLLING_RX -- For Reception mode Interrupt driven without communication buffer: Data can be Transmitted/Received both in single as well as continuous mode through the interrupt driven mechanism. In the continuous mode the user data is directly being read/written from/to the addresses passed by the user. After each byte of data transfer an interrupt is acknowledged and the control goes to the interrupt subroutine. The main advantage of using interrupts rather than polling is that control does not stay in the function till the last data is Transmitted/Received and hence the SPI can be used in full duplex mode. Here you should take care not to read/write the user buffer until the Transmission/Reception completion. To use this mode you must select the following # define labels inside the ST7lib_config.h file: SPI_ITDRV_WITHOUTBUF_TX -- For Transmission SPI_ITDRV_WITHOUTBUF_RX -- For Reception Notes: 1. If both SPI_ ITDRV_WITHOUTBUF_TX and SPI_ITDRV_WITHOUTBUF_RX are defined in full duplex mode, then the program will perform either transmission or reception (only transmission as per the present structure) since, the peripheral has a single interrupt for both Transmission and Reception completion. Because of this correct full duplex communication will be prevented. In order to operate the SPI in Full Duplex Mode, it is required that either the

18/235

How to use the library

Transmission or Reception is performed in Polling Mode and the other in Interrupt Driven Mode. So, you can use any one of the following combinations in full duplex mode. SPI_POLLING_TX -- For Transmission mode SPI_ITDRV_WITHOUTBUF_RX -- For Reception (or) SPI_ITDRV_WITHOUTBUF_TX -- For Transmission SPI_POLLING_RX -- For Reception mode 6.2.3 I2C This part of the user manual contains the detailed description of all the functions for I2C. An example C program has been given at the end. You can select either of the two Transmission/ Reception modes implemented in the library. To select any of the possible modes described below, you need to select the corresponding #define statement inside the ST7lib_config.h file. Polling: With this mechanism the data can be transmitted or received by polling the status of the corresponding flag. Either single or continuous Transmission/Reception is possible. In continuous Transmission/Reception control stays inside the function until all the requested data is Transmitted/Received and hence the application software risks losing control if there is a breakdown in communication (if the I2C mode is disabled). To avoid the risk, the appplication can use single byte transmission with some timeout protection. This mechanism can only be used with the I2C in half duplex mode. To use this mode, you must have selected the following # define labels in the ST7lib_config.h file: I2C_POLLING_TX -- For Transmission mode I2C_POLLING_RX -- For Reception mode Interrupt driven without communication buffer Data can be Transmitted/Received both in single as well as continuous mode through the interrupt driven mechanism. In continuous mode the user data is directly read/written from/to the addresses passed by the user. After each byte of data transfer an interrupt is acknowledged and the control goes to the interrupt subroutine. The advantage of using interrupts rather than polling is that control does not stay in the function till the last data is Transmitted/Received. Here, care should be taken not to read/write the user-buffer until the Transmission/Reception c o m p l e t e s . To use this mode, you must select the following # define labels inside the ST7lib_config.h file: I2C_ITDRV_WITHOUTBUF_TX -- For Transmission I2C_ITDRV_WITHOUTBUF_RX -- For Reception Master Receiver Communication Methodology: In Master receiver mode, to close the communication the STOP bit must be set to generate a stop condition, before reading the last byte from the DR register. In order to generate the nonacknowledge pulse after the last received data, the ACK bit must be cleared just before reading the second last byte. The following flowchart shows the management of the ACK and STOP bits, when the master is receiving.

19/235

How to use the library

For Example, if `N' Bytes to be received,

: : : When`N-2' byte is received Read I2CDR Wait for BTF = 1

When `N-1' byte is received

Clear ACK in I2CCR Read I2CDR Wait for BTF = 1

When `N'th byte is received

Set STOP in I2CCR Read I2CDR

In I2C_GetBuffer, the ACK and STOP bits are automatically managed inside the function. In I2C_GetByte you must manage the ACK and STOP bits as shown below, in order to receive only one byte.

20/235

How to use the library

Figure 3. Flow-Chart for single byte reception in Master mode

I2C_Load_Address (send slave address)

Waiting for completion of event EV6 (wait for EVF=1)

Read I2CSR1 Clear ACK in I2CCR register by using the function I2C_ACK

Wait for BTF = 1

Set STOP in I2CCR

I2C_GetByte

6.2.4 CAN This Section gives an overview of the user guidelines for the CAN Library. The library provides the software routines to use the CAN peripheral for ST72F561 device. The library is based on the HIS / Vector CAN driver specification. The implemented function list is a subset of the functions described in the HIS / Vector CAN driver specification document.

21/235

How to use the library

6.2.4.1 DESCRIPTION Files Can.c - This file contains the CAN driver source code. Can.h - This file contains the data structure, data type definitions and function prototypes for the driver functions. Can_hr.h - This file contains the #define statements for the driver functions. User.c - This file contains the Global data declaration which is used by both driver as well as application. For example - Tx & Rx buffers, Tx & Rx Id, Confirmation & Indication flags etc. User.h - This file contains all user configurable parameters. For example- size of Tx & Rx buffers, Number of Tx & Rx messages, hardware registers initialization values etc. Note: User.c and User.h can be configured by the user depending on the application. 6.2.4.2 DATA STRUCTURES Init Structure Init structure contains the initialization values for the CAN controller registers. The user applic a t i o n may have more than one Init Structures which is configured by the parameter NO_OF_INIT_HANDLES. The init handle is used as an index for the init structure. Transmit Structure The transmit structure contains the information about the transmitted message, for example tx_Id, tx_dlc, tx_buffer. There is a separate table each for Id, dlc, pointer to tx_buffer. The number of transmit structures depends on the number of messages to be transmitted in an application. It is configured by the parameter NO_OF_TX_HANDLES. The tx_handle is used as an index for each transmit structure. The tx_identifier has two tables: one table each for standard and extended identifiers. The tx_id, tx_dlc tables are configured by the user as per the message to be transmitted. There is a single bit confirmation flag for each transmit message. Receive Structure The receive structure contains the information about the received message, for example rx_Id, rx_dlc, rx_buffer. There is separate table each for Id, dlc, pointer to rx_buffer. The number of receive structures depends up on number of messages to be received in an application. It is configured by the parameter NO_OF_RX_HANDLES. The rx_handle is used as an index for each receive structure. The rx_identifier has two tables: one table each for standard and ex tended identifiers. The identifier for the received message is stored inside this table by the driver. The rx_dlc is configured by the user as per the length of the message. There is a single bit indication flag and overflow flag for each received message.

22/235

How to use the library

6.2.4.3 DATA TYPES The following are the data types used by the drivercanuint8 canuint16 8-bit unsigned integer 16-bit unsigned integer

There are some data types referenced while calling driver function CanInitHandle 8-bit unsigned integer (application-specific, depends on the number of configured initialization modes). CanTransmitHandle 8-bit unsigned integer (application-specific, depends on the number of transmit objects).
tCanMsgObject typedef volatile struct { canuint16 stdid; canuint16 extid; canuint8 dlc; canuint8 data[8]; }

This is a transmit message structure referenced for the CAN driver service CanMsgTransmit(). 6.2.4.4 MEMORY USAGE Constants This includes the initialization values inside the Init Structure for the CAN controller registers, transmit message information(tx_id, tx_dlc) inside the transmit structure, and receive message information(rx_dlc). These are stored in ROM. Global Variables These include the transmit & receive buffers, confirmation & indication flags, pointers to the Tx & Rx buffers, and receive message id's(rx_id). 6.2.4.5 PARAMETER CONFIGURATION There are certain parameters that you have to configure depending on the application. These parameters are configured inside the files user.c & user.h. The following are the parameters that must be configured in the file user.h 1. NO_OF_TX_HANDLES - This parameter defines the number of messages to be transmitted by the application. 2. NO_OF_RX_HANDLES- The number of messages to be received by the application which depends on the number of messages configured in the filter registers. 3. NO_OF_INIT_HANDLES- The number of initialization structures required in an application. By default, its value is set to 1.

23/235

How to use the library

4. TX_MSGx_STDID - The standard id part for the MSGx to be transmitted, where x = transmit message number. 5. TX_MSGx_EXTID - The extended id part for the MSGx to be transmitted, where x = transmit message number. 6. TX_MSGx_DLC - The length for the MSGx to be transmitted, where x = transmit message number. The maximum length that can be defined is 8. 7. RX_MSGx_DLC - The length for the MSGx to be received, where x = receive message number. The maximum length that can be defined is 8. 8. REG_INITx_VALUE - The register initialization value for the CAN controller register, where REG - register name, x = init structure number. The following are the parameters that must be configured in the file user.c 1. MSGx_Tx_Buffer - This declares the buffer for the MSGx to be transmitted. The length of the buffer is the same as defined by the parameter TX_MSGx_DLC in the file user.h. The n u m b e r of such buffers to be declared is the same as defined by the parameter NO_OF_TX_HANDLES in the file user.h. 2. tx_stdid[ ] - This table stores the standard id value/s for the message/s to be transmitted. The length of the table is the same as defined by the parameter NO_OF_TX_HANDLES and the value/s stored inside is/are the same as defined by the parameter TX_MSGx_STDID in the file user.h. If the message to be transmitted is Extended then above has to logical-ORed with the EXT_ID_MASK(IDE bit), EXID17 & EXID16 bit values. As a result, the values stored inside the table are in the same format as of MIDR0 & MIDR1 registers. 3. tx_extid[ ] - This table stores the extended id value/s for the message/s to be transmitted. The length of the table is the same as defined by the parameter NO_OF_TX_HANDLES and t h e value/s stored inside the table is/are the same as defined by the parameter TX_MSGx_EXTID in the file user.h. It stores the values into the same format as of MIDR2 & MIDR3 registers. 4. tx_dlc[ ] - This table stores the length for the message/s to be transmitted. The length of the table is the same as defined by the parameter NO_OF_TX_HANDLES and the value/s stored inside the table is/are the same as defined by the parameter TX_MSGx_DLC in the file user.h. 5. tx_data_ptr[ ] - This pointer table stores the address of transmit buffer/s (MSGx_Tx_buffer). The length of the table is the same as defined by the parameter NO_OF_TX_HANDLES in the file user.h. 6. MSGx_Rx_Buffer - This declares the buffer for the MSGx to be received. The length of the buffer is the same as defined by the parameter RX_MSGx_DLC in the file user.h. Number of such buffers to be declared is the same as defined by the parameter NO_OF_RX_HANDLES in the file user.h.

24/235

How to use the library

7. rx_stdid - This declares the memory for storing the standard id part of the message to be received. The length of the table is the same as defined by the parameter NO_OF_RX_HANDLES in the file user.h. 8. rx_extid - This declares the memory for storing the extended id part of the message to be received. The length of the table is the same as defined by the parameter NO_OF_RX_HANDLES in the file user.h. 9. rx_dlc[ ] - This table stores the length for the message/s to be received. The length of the table is the same as defined by the parameter NO_OF_RX_HANDLES and the value/s stored inside the table is/are the same as defined by the parameter TX_MSGx_DLC in the file user.h. 10. rx_data_ptr[ ] - This pointer table stores the address of receive buffer/s ( M S G x _ R x _ B u f f e r ) . The length of the table is the same as defined by the parameter NO_OF_RX_HANDLES in the file user.h. 6.2.4.6 Tx & Rx BUFFER USAGE Data can be accessed through the Tx & Rx buffers using the tx_handle & rx_handle as an i n d e x . For example, data can be written into the MSGx_Tx_Buffer using the pointer tx_data_ptr[x], where x = tx_handle for the message. Similarly, data can be received from MSGx_Rx_Buffer using the pointer rx_data_ptr[x], where x = rx_handle for the message. 6.2.4.7 IMPLEMENTATION HINTS CanSleep( ) service must not be called when message transmission is in progress otherwise sleep mode is not entered and service returns KCANFAILED. Also CanTransmit( ) service shall not be called while the CAN driver is in sleep mode. Confirmation flag is set by the driver after the successful transmission of a message and flag has to be cleared by the application. Application must call CanInterruptDisable( ) and CanInterruptRestore( ) services when clearing the confirmation flag in order to avoid CAN interrupt. Indication flag is set by the driver for a message received and this flag has to be cleared by the application. Application must call CanInterruptDisable( ) and CanInterruptRestore( ) services when clearing the indication flag in order to avoid CAN interrupt. Overflow flag is set by the driver if the indication flag is not cleared by the application or message is not copied by the application from the global buffer into the application buffer. If the overflow is set it means that the new message has been overwritten over the previous message. Overflow flag has to be cleared by the application. Application must call CanInterruptDisable( ) and CanInterruptRestore( ) services when clearing the overflow flag in order to avoid CAN interrupt. While copying data from receive buffer, application must call CanInterruptDisable( ) and CanInterruptRestore( ) services in order to avoid a CAN interrupt. Similarly, while copying

25/235

How to use the library

data into the transmit buffer, application must call CanInterruptDisable( ) and CanInterruptRestore( ) services to avoid an interrupt. 6.3 OTHER PERIPHERALS 6.3.1 TIMER TIMERA and TIMERB can both be used simultaneously, depending on the TIMER selected. You have to define USE_TIMERA and/or USE_TIMERB in ST7lib_config.h. Each function name in the user manual contains TIMERx where x can be A or B depending on whether it is for TIMERA or TIMERB. This is also explained in the example given at the end of the TIMER library. 6.3.2 I/O You must select the following parameters as per the device package. # d e f i n e IO_521_80PIN - Select this for an 80-pin package for ST72F521 device ST7lib_config.h file. # d e f i n e IO_62_42PIN - Select this for a 42-pin package for ST72F62 device ST7lib_config.h file. # d e f i n e IO_62_32PIN - Select this for a 32-pin package for ST72F62 device ST7lib_config.h file. I f you are using other device packages, you must comment out these declarations ST7lib_config.h file. 6.4 MEMORY MODELS Limitation: in Cosmic, you are not allowed to use the same function in both the main program and interrupt subroutine. This will give the error of Reentrant function in all memory models except mods and modsl. 6.5 PORTING APPLICATIONS FROM LIBRARY VERSION 1.0 Applications can be ported easily from ST7 Library Version 1.0 to ST7 LIbrary Version 2.0 by making the following changes: Change the configuration files st7lib_config.h, default.env, .mak, .prm, and .lkf Add device_reg.o in compile list and link list in .mak, .prm and .lkf files Remove inclusion of periph_hr.h files from main to access device registers directly Replace use of TIMERA, TIMERB macros with USE_TIMERA, USE_TIMERB Replace ITC_EXT_ITSensitivity with ITC_ConfigureInterrupt Refer to the Release Notes for the list of changes in new version in in in in

26/235

Presentation of library functions

7 PRESENTATION OF LIBRARY FUNCTIONS
7.1 LIBRARY REFERENCES Functions are described in the format given below: Function name Peripheral name and main functionality covered Function prototype Prototype declaration Behaviour Description Brief explanation of how the functions are executed Input Parameters Description of the parameters to be passed Output Parameters Value returned by the function Required preconditions Specific requirements to run the function Functions called Library Functions called Post conditions Function required to call immediately after this function See also Related functions for user reference Note Important points that you must take into consideration Caution Important points to be considered to avoid any failures Code example Example to show the proper way to use the library functions

27/235

Release Information

8 RELEASE INFORMATION
This release supports the following peripherals and devices. 8.1 PERIPHERALS ADC (8-bit and 10bit): The on-chip Analog to Digital Converter (ADC) peripheral is a 10-bit, successive approximation converter with internal sample and hold circuitry. SCI (with/without extended Baud Rate Pre scalar): The Serial Communications Interface (SCI) offers a flexible means of full-duplex data exchange with external equipment requiring an industry standard NRZ asynchronous serial data format. SPI: The Serial Peripheral Interface (SPI) allows fullduplex, synchronous, serial communication with external devices. I2C single/multi master: The Inter-Integrated Circuit Bus Interface serves as an interface between the microcontroller and the serial I2C bus. I2C Slave 16-bit Timer: The timer consists of a 16-bit free-running counter driven by a programmable prescaler. 8-bit Timer: The timer consists of a 8-bit free-running counter driven by a programmable prescaler. 8-bit Lite timer: The Lite Timer can be used for general-purpose timing functions. PWM ART 8-bit: The Pulse Width Modulated Auto-Reload Timer on-chip peripheral consists of an 8-bit auto reload counter with compare/capture capabilities and of a 7-bit prescaler clock source. AR 12-bit timer: The 12-bit Autoreload Timer can be used for general-purpose timing functions. TBU: The Timebase unit (TBU) can be used to generate periodic interrupts. WDG: The Watchdog timer is used to detect the occurrence of a software fault. ITC: The Interrupt Controller manages the hardware and software interrupts with flexible interrupt priority and level configuration. MCC: The Main Clock Controller consists of a programmable CPU clock prescaler, a clockout signal to supply external devices and a real time clock timer with interrupt capability. EEPROM: The Electrically Erasable Programmable Read Only Memory can be used as a non volatile backup for storing data. I/Os: An I/O port contains up to 8 pins. Each pin can be programmed independently as digital input (with or without interrupt generation) or digital output. CAN: The Controller area Network peripheral allows communication over a CAN network.

28/235

Release Information

8.2 DEVICES ST72F62 ST72F63B ST72F65 ST72F521 ST7FLITE0 ST7FLITE1 ST7FLITE2 ST7FLITE3 ST72F264 ST72F561 ST7SUPERLITE ST72325 ST7232A

29/235

Function Descriptions

9 FUNCTION DESCRIPTIONS 9.1 GENERAL PURPOSE PERIPHERALS 9.1.1 ADC This software library consists of the following functions for 8-bit and 10-bit ADC.
Function Name Function Prototype ADC_Init Void ADC_Init (Typ_ADC_InitParameter InitValue) Initialization of the ADC, sets by default, channel to AIN0, speed to default value of the device, ADC off, amplifier off, interrupt disable and Continous conversion mode. You can pass one or more input parameters by logically ORing them together to change the default configuration. ADC_SPEED 1) Fadc=Fcpu/4 or Fcpu/2 or Fcpu, depending upon the device selected. ADC_SLOW 2) It is used together with ADC_SPEED to configure ADC clock for device. ADC_ONESHOT 3) Input Parameters One shot conversion active ADC_AMPLIFIER_ON 4) Amplifier on AD C_D E FAULT sets ADC in default configuration. ADC_IT_ENABLE 3) Interrupt enable for end of conversion. Output Parameters Required Preconditions Functions called Postconditions See also None 1. Configure IO properly. 2. Selection of the right ADC in the file ST7lib_config.h No n e ADC correctly configured ADC_Enable and ADC_Select_Channel

Behaviour Description

1)Speed bit is present in ST72F561, ST72F62, ST72F264, ST72F521, ST72325, ST7232A, ST7DALI, ST7FLITE0/1/2/3 and ST7SUPERLITE. 2)Slow bit is present in ST72F561, ST72F264, ST7DALI, ST7FLITE0/1/2/3 and ST7SUPER LITE. 3)Feature present only in ST72F62. 4)Amplifier present in ST7DALI, ST7FLITE0/1/2 and ST7SUPERLITE.

30/235

Function Descriptions

Table 2. ADC_Select_Channel
Function Name Function Prototype Behaviour Description ADC_Select_Channel Void ADC_Select_Channel (unsigned char ADC_AIN) Selects the conversion channel by passing the channel number as input parameter ADC_AIN Input Parameters ADC_AIN is in the range [0:15] The channel number depends on the device, please refer to the corresponding datasheet. None 1. `ADC_Init' must have been called. Required Preconditions Functions called Postconditions See also 2. The selected channel must be configured as floating input. No n e ADC channel selected ADC_Enable

Output Parameters

Table 3. ADC_Enable
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also ADC_Enable Void ADC_Enable (void) Switches on the ADC to start conversion on the selected channel. None None ADC_Select_Channel must have been called. No n e ADC conversion started ADC_Disable

31/235

Function Descriptions

Table 4. ADC_Test_Conversn_Complete
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called ADC_Test_Conversn_Complete BOOL ADC_Test_Conversn_Complete (void) Returns the latest status of conversion None TRUE: conversion completed FALSE: conversion not completed ADC_Enable must have been called. No n e If TRUE, ADC conversion is complete and you can call the ADC_Conversn _Read. If FALSE, ADC conversion not completed. This function can be looped until the conversion is complete. See also ADC_Disable, ADC_Conversn_Read

Postconditions

Table 5. ADC_Conversn_Read
Function Name ADC_Conversn_Read For 10-bit ADC, Function Prototype unsigned int ADC_Conversn_Read (void) For 8-bit ADC, unsigned char ADC_Conversn_Read (void) Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also Reads the converted digital value from the data register. None Data Register value (it depends upon the device selected, please refer to the corresponding data sheet). ADC_Test_Conversn_Complete must have been called. No n e 1. EOC flag is cleared. 2. Equivalent digital value available in the data register is returned. None

Note: The EOC flag may be set again during the execution of this function, this depends on the conversion time.

32/235

Function Descriptions

Table 6. ADC_Disable
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also ADC_Disable Void ADC_Disable (void) Stops ADC conversion on the selected channel. None None ADC is switched on No n e ADC switched off ADC_Enable

Example: The following C program shows the use of the ADC functions. Program description: This program converts the analog value on channel 5 of the ST72F62 device to a digital value.
/* Program start */ #include "st7lib_config.h" void main (void); void main(void) { unsigned int Conv_Data1; unsigned char channel = 5; /* Select st72F62 device */

/* Variable to get the converted digital value

*/

ADC_Init ((unsigned char )ADC_SPEED | (unsigned char )ADC_ONESHOT); /* FADC= FCPU/4 */ ADC_Select_Channel (channel); /* Channel 5 selected */ ADC_Enable (); /* Start conversion */ while (ADC_Test_Conversn_Complete () == FALSE); Conv_Data1 = ADC_Conversn_Read (); /* Read the converted value */ ADC_Disable () ; Nop; /* Macro defined in st7lib_config.h */ } /* Program end */

33/235

Function Descriptions

9.1.2 SCI This Library supports 2 SCI of ST72F561 device and 1 SCI on all other devices. For devices with only one SCI no suffix "x" is used in the function names. For 2nd SCI of ST72F561 you must replace suffix "x" in the function names with 2.
Function Name Function Prototype SCIx_Init Void SCIx_Init (SCI_Type_Param1 Init_Value1, SCI_Type_Param2 Init_Value2) Initialization of SCI, sets by default receiver sleep off, no break character will be transmitted, wakeup from sleep by idle frame detection, Parity disabled, 8-bit transmission mode and Receiver in active mode. You can select the parity, 9-bit transmission mode, Receiver wakeup, Receiver Mute and Break Enable feature through properly selecting the Init_Value1 and Init_Value2. SC I_OD PARITY_SELEC T Select odd Parity SCI_EVPARITY_SELECT Select even parity SC I_WAKE UP_ADD R Input Parameter 1 Receiver wake up from mute mode while address mark is detected(i.e MSBit of the data transmitted should be 1) SCI_WORDLENGTH_9 Select 9-bit transmission SC I_DEFAULT_PARA M1 Load the register with the default value(0x00) SC I_MU TE _EN ABLE Receiver in mute mode Input Parameter 2 SC I_BREA K_ENAB LE Transmit break characters SC I_DEFAULT_PARA M2 Load the register with the default value(0x00) Output Parameter Required Preconditions None SCI port pin should be configured properly.

Behaviour Description

34/235

Function Descriptions

Table 7. SCIx_Compute_Baudrate
Function Name Function Prototype Behaviour Description Input Parameter 1 Input Parameter 2 Output Parameter Required Preconditions Functions called Postconditions SCIx_Compute_Baudrate Void SCIx_Compute_Baudrate(unsigned int BaudRate_Tx, unsigned int BaudRate_Rx) Selects Transmitter/ Receiver baudrate for the SCI without extended prescaler. BaudRate_Tx* You can select any possible baudrate for transmission. BaudRate_Rx* You can select any possible baudrate for reception. No n e 1. SCIx_Init, must have been called. 2. fcpu must have been defined in ST7lib_Config.h No n e None

Note: This function takes a large ROM area as calculations for TR, RR and PR are done inside the function. However, you can choose to pass the baudrate directly. If the selected baudrate speed is not possible, the closest possible value will be used. If there is no common prescalar factor for receiver and transmitter baudrates, then you will get the nearest possible receiver baudrate, at the prescalar division factor selected for the transmitter. In half Duplex mode you can pass the same transmitter and receiver baudrates to get the exact Tx/Rx baudrate (whichever mode you are using)

35/235

Function Descriptions

Table 8. SCIx_Select_Baudrate
Function Name Function Prototype SCIx_Select_Baudrate Void SCIx_Select_Baudrate (SCI_Baudrate_Type Baudrate_Prescaler) Selects Transmit/Receive baudrate for SCI without extended baudrate prescaler. You have to define all the prescaler parameters corresponding to the desired baudrate speed. You have to pass the three input parameters by logically ORing them to select the baudrate. SCI_PR _X X=1,3, 4,13 Input Parameters SCI_TR_Y Y=1,2,4,8,16,32,64,128 SCI_RR_Z Z=1,2,4,8,16,32,64,128 Output Parameter Required Preconditions Functions called Postconditions S CI _ P R _ X SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_TR_Y SCI_TR_1 SCI_TR_2 SCI_TR_4 SCI_TR_8 SCI_TR_16 SCI_TR_32 No n e 1.SCIx_Init must have been called 2. You have to specify the PR, RR and TR values for the desired baudrate No n e Refer to the table below. SCI_RR _Z SCI_RR_1 SCI_RR_2 SCI_RR_4 SCI_RR_8 SCI_RR_16 SCI_RR_32 Transmitter baudrate speed 38400 19200 9600 4800 2400 1200 Receiver baudrate Speed 38400 19200 9600 4800 2400 1200

Behaviour Description

Note: This function saves the ROM area but you have to pass the values for the TR,PR RR.

36/235

Function Descriptions

Table 9. SCIx_Extend_Baudrate
Function Name Function Prototype SCIx_Extend_Baudrate Void SCIx_Extend_Baudrate (SCI_Baudrate_Type Baudrate_Prescaler, unsigned char EPTR, unsigned char EPRR) Selects Transmit/Receive baudrate for SCI with extended baudrate prescaler. You have to define all the prescaler parameters corresponding to the desired baudrate speed. SCI_PR _X X=1,3, 4,13 Input Parameter 1 SCI_TR_Y Y=1,2,4,8,16,32,64,128 SCI_RR_Z Z=1,2,4,8,16,32,64,128 Input Parameter 2 Input Parameter 3 Output Parameter Required Preconditions Functions called Postconditions EPTR Select any value from 0 to 255 EPR R Select any value of EPRR from 0 to 255 No n e 1.SCIx_Init must have been called 2. You have to specify the PR, RR and TR values for the desired baudrate No n e Refer to the table below.

Behaviour Description

SCI_PR_X SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13 SCI_PR_13

TR _Y SC I_T R_1 SC I_T R_2 SC I_T R_4 SC I_T R_8 SC I_T R_16 SC I_T R_32

RR _Z SC I_RR _1 SC I_RR _2 SC I_RR _4 SC I_RR _8 SC I_RR _16 SC I_RR _32

EPTR 1 2 3 4 5 6

EPRR 1 2 3 4 5 6

Transmitter baudrate speed 38400 9600 3200 1200 480 200

Receiver baudrate Speed 38400 9600 3200 1200 480 200

37/235

Function Descriptions

Table 10. SCIx_IT_Enable
Function Name Function Prototype Behaviour Description SCIx_IT_Enable Void SCIx_IT_Enable (SCI_IT_Type SCI_IT_Param) Selects SCI interrupts SCI_IDLE_LINE Enable interrupt due to idle frame reception. SCI_R ECEIVE_OVER RUN Enable interrupt due to data reception or overrun error. S C I _ T R A NS M I T _ R E G I S T E R _ R E A D Y Input Parameters Enable interrupt when transmit data register is ready to load. SCI_FRAME_TRANSMITTED Enable Interrupt due to Transmission completetion. SCI_PA RITY_ERR OR Enable Interrupt due to Parity Error. Output Parameter No n e 1. SCIx_ComputeBaudrate or SCIx_SelectBaudrate must have been called. 2. You should reset the interrupt mask with EnableInterrupts. No n e None None

Required Preconditions

Functions called Postconditions See also

38/235

Function Descriptions

Table 11. SCIx_IT_Disable
Function Name Function Prototype Behaviour Description SCIx_IT_Disable Void SCIx_IT_Disable (SCI_IT_Type SCI_IT_Param) Disables SCI interrupts SCI_IDLE_LINE Disable interrupt due to idle frame reception. SCI_R ECEIVE_OVER RUN Disable interrupt due to data reception or overrun error. S C I _ T R A NS M I T _ R E G I S T E R _ R E A D Y Input Parameters Disable interrupts triggered when transmit data register is ready to load. SCI_FRAME_TRANSMITTED Disable Interrupt due to Transmission completion. SCI_PA RITY_ERR OR Disable Interrupt due to Parity Error. Output Parameters Required Preconditions. Functions called Postconditions See also None The baudrate must have been selected No n e None None

Table 12. SCIx_Mode
Function Name Function Prototype Behaviour Description SCIx_Mode Void SCIx_Mode (SCI_Mode_Type SCI_Mode_Param) Enables Transmitter/Receiver mode of SCI. SCI_TX_ENA BLE Input Parameter Enable the Transmitter mode. SCI_R X _E NABLE Enable the Receiver mode. Output Parameter Required Preconditions Functions called Postconditions See also No n e SCIx_IT_Enable must have been called for interrupt mode No n e None None

Note: To disable the SCI Mode, select the SCIx_Init function.

39/235

Function Descriptions

Table 13. SCIx_PutByte
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters SCIx_PutByte Void SCIx_PutByte (unsigned char Tx_Data) Transmits a single byte of data polling mode or interrupt driven mode. Tx_Data Data byte to be transmit. None 1. SCIx_Mode must have been called. 2. SCIx_IsTransmitCompleted must have been called (Refer to example on page 53 for more details). Required Preconditions 3. You must enable the interrupt due to Transmit Complete/Transmit Data Ready Flag for the Interrupt driven mode 4. You must select Polling or Interrupt driven Transmission mode in ST7lib_config.h Functions called Postconditions See also No n e None None

Notes: You can use some timeout protection while using this function. This function is for Polling or Interrupt driven mode.

Table 14. SCIx_IsTransmitCompleted
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also SCIx_IsTransmitCompleted BOOL SCIx_IsTransmitCompleted (void) Checks for the completion of current byte transmission. Returns TRUE if byte transmission is completed otherwise returns FALSE. None Boolean SCIx_PutByte must have been called. No n e None None

Note: This function is for Polling mode.

40/235

Function Descriptions

Table 15. SCIx_PutBuffer
Function Name Function Prototype Behaviour Description SCIx_PutBuffer Void SCIx_PutBuffer(const unsigned char *PtrToBuffer, unsigned char NbOfBytes) Starts transmission from the user buffer. The data transmission will be driven either in Polling or Interrupt driven mode depending on the mode you selected. *PtrToBuffer Start address of the user buffer NbOfBytes Number of bytes to be transmitted No n e 1. SCIx_Mode must have been called. 2. You must enable the interrupt due to Transmit Data Ready Flag for the Interrupt driven mode Required Preconditions 3. You must select the Polling or Interrupt driven transmission mode in ST7lib_Config.h file. 4. The SCIx_IT_Function must have been called inside the SCI interrupt subroutine. Functions called Postconditions See also SCIx_IsTransmitCompleted None None

Input Parameter 1 Input Parameter 2 Output Parameter

Note: This function is for Polling or Interrupt driven mode. Caution: The application can lose control if the SCI is disabled while using this function in polling mode. Take care not to access the user buffer until transmission is complete.

41/235

Function Descriptions

Table 16. SCIx_PutString
Function Name Function Prototype Behaviour Description SCIx_PutString Void SCIx_PutString (const unsigned char *PtrToString) Starts transmission of a string passed by the user. The data transmission will be through polling or interrupt driven modes depending on the mode you selected. *PtrToString Start address of the user string None 1. SCIx_Mode must have been called. 2. You must enable the interrupt due to Transmit Data Ready Flag for Interrupt driven mode. Required Preconditions 3. You must select the transmission mode Polling or Interrupt driven in ST7lib_Config.h. 4. SCIx_IT_Function must have been called inside the SCI interrupt subroutine. Functions called Postconditions See also SCIx_IsTransmitCompleted None None

Input Parameters Output Parameters

Note: This function is for Polling or Interrupt driven mode. Caution: The application can lose control if the SCI is disabled while using this function in polling mode. Take care not to access the string until transmission is complete. Table 17. SCIx_IsTransmitCompleted
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also SCIx_IsTransmitCompleted BOOL SCIx_IsTransmitCompleted (void) Checks for the completion of data transmission. It returns FALSE till all the data bytes have been transmitted and TRUE when the request is over. None Boolean Transmission must have been requested. No n e SCIx_PutByte/SCIx_PutBuffer/SCIx_PutString must be called after this function None

Note: This function is for Interrupt driven mode.

42/235

Function Descriptions

Table 18. SCIx_9thBit_TxRx
Function Name Function Prototype Behaviour Description SCIx_9thBit_TxRx BOOL SCIx_9thBit_TxRx (BOOL Bit9_Val) This function configures the 9th bit to be transmitted as 0 or 1 for 9-bit transmission. Also it returns the status of the 9th bit in the 9-bit reception mode. TRUE Input Parameters If 1 is to be transmitted as 9th bit. FALSE If 0 is to be transmitted as 9th bit. TRUE Output Parameters If 9th bit received is 1. FALSE If 9th bit received is 0. 1.SCI must be configured in 9 bit mode. Required Preconditions Functions called Postconditions See also 2.For reception function SCIx_GetString/SCIx_GetBuffer/ SCIx_GetByte must have been called before this function. No n e For transmission SCIx_PutByte/SCIx_PutBuffer/ SCIx_PutString must be called after this function. None

Notes: In transmission, the return value of the function is ignored. In reception, the input parameter is not significant. You must call this function while using 9 bit mode. The Status of the 9th bit remains same during the complete buffer/string transmission. You can change the status of 9th bit in the next request.

43/235

Function Descriptions

Table 19. SCIx_GetByte
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters SCIx_GetByte Unsigned char SCIx_GetByte (void) Returns the most recent Byte received in Polling or Interrupt driven mode. None Unsigned char Received data byte 1. The SCIx_Mode must have been called 2. You must have called SCIx_IsReceptionCompleted to check the reception status. Required Preconditions 3. You must enable the interrupt due to Receive Data Ready flag for Interrupt driven mode. 4. You must select Polling or Interrupt driven Reception mode in ST7lib_Config.h. 5. For Interrupt driven mode SCIx_IT_Function must have been called inside the SCI interrupt subroutine. Functions called Postconditions See also No n e None None

Notes: You can use some timeout protection while using this function. This function can be used in Polling or Interrupt driven mode.

44/235

Function Descriptions

Table 20. SCIx_GetBuffer
Function Name Function Prototype SCIx_GetBuffer SCI_RxError_t SCIx_GetBuffer (unsigned char *PtrToBuffer, unsigned char NbOfBytes) Receives a number of data bytes and stores them in the user buffer. The reception stops as soon as an error occurs and error status is returned. The data reception is controlled by polling. *PtrtoBuffer Start address of the user buffer NbOfBytes Total number of bytes to be received SCI_NOISE_ERR Noise error occurred during transmission. SCI_OVER RUN_ERR Overrun error occurred during reception Output Parameters SCI_FRAMING_ERR Framing error occurred during reception SCI_PA RITY_ERR Parity error occurred during reception SCI_R ECEIVE_OK Error free reception 1.The SCIx_Mode must have been called. Required Preconditions Functions called See also 2.You must select Polling reception mode in ST7lib_Config.h No n e SCIx_GetBuffer (Interrupt driven mode)

Behaviour Description

Input Parameter 1 Input Parameter 2

Note: This function is only for Polling mode Caution: The application can lose control if the SCI is disabled while using this function in polling mode.

45/235

Function Descriptions

Table 21. SCIx_GetString
Function Name Function Prototype SCIx_GetString SCI_RxError_t SCIx_GetString (unsigned char *PtrToString) Receives and stores the data in the user-defined string. The reception stops as soon as an error occurs and error status is returned. The data reception is controlled by polling . *PtrToString Start address of the String SCI_NOISE_ERR Noise error occurred during reception. SCI_OVER RUN_ERR Overrun error has occurred during reception Output Parameters SCI_FRAMING_ERR Framing error occurred during reception SCI_R ECEIVE_OK Error free reception SCI_PARITY_ERR Parity error occurred during reception 1. SCIx_Mode must have been called Required Preconditions Functions called Postconditions See also 2. You must select Polling reception mode in ST7lib_Config.h No n e None SCIx_GetString (Interrupt driven mode)

Behaviour Description

Input Parameters

Note: This function is only for Polling mode Caution: The application can lose control if the SCI is disabled while using this function in polling mode.

46/235

Function Descriptions

Table 22. SCIx_GetBuffer
Function Name Function Prototype Behaviour Description Input Parameter 1 Input Parameter 2 Output Parameters SCIx_GetBuffer Void SCIx_GetBuffer (unsigned char *PtrToBuffer, unsigned char NbOfBytes) Starts reception of the bytes and stores it into the userbuffer in interrupt driven mode. *PtrToBuffer Start address of the user buffer NbOfBytes Total number of bytes to be received None 1. The SCIx_Mode must have been called 2. You must enable the interrupt due to Receive Data Ready flag. Required Preconditions 3. You must select the Interrupt driven reception mode in ST7lib_Config.h 4. SCIx_IT_Function must have been called inside the SCI interrupt subroutine. Functions called Postconditions See also No n e You must call SCIx_IsReceptionCompleted after this function to check the reception status. SCIx_GetBuffer (Polling mode)

Note: This function is only for Interrupt driven mode. Caution: Take care not to access the user buffer until reception is completed. Any data received before calling this function is ignored The data reception will stop as soon as an error occurs.

47/235

Function Descriptions

Table 23. SCIx_GetString
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters SCIx_GetString Void SCIx_GetString (unsigned char *PtrToString) Reception of data string starts through interrupt driven mode *PtrToString Start address of the location where string is to be placed. None 1. SCIx_Mode must have been called 2. You must enable the interrupt due to Receive Data Ready flag. Required Preconditions 3. You must select the Interrupt driven reception mode in ST7lib_Config.h. 4. SCIx_IT_Function must have been called inside the SCI interrupt subroutine. Functions called Postconditions See also No n e You must call SCIx_IsReceptionCompleted after this function to check the reception status. SCIx_GetString (Polling mode)

Note: This function is only for Interrupt driven mode. Caution: Take care not to access the user buffer until reception is completed Any data received before calling this function is ignored The data reception will stop as soon as an error occurs.

48/235

Function Descriptions

Table 24. SCIx_IsReceptionCompleted
Function Name Function Prototype SCIx_IsReceptionCompleted SCI_RxError_t SCIx_IsReceptionCompleted(void) In Interrupt driven mode, this function checks for the completion of reception of a set of data or the occurrence of an error and returns the reception status. Behaviour Description In both Polling and Interrupt driven modes, the function checks if a single byte of data is received and ready for processing. It returns SCI_RX_DATA_EMPTY until the data byte is received and returns the reception status afterwards. None SCI_BUFFER_ONGOING 1) User buffer is not full SCI_STRING_ONGOING 1) Complete string is not received in the user buffer SCI_NOISE_ERR Noise error occurred during reception. SCI_OVER RUN_ERR Output Parameters Overrun error occurred during reception SCI_FRAMING_ERR Framing error occurred during reception SCI_R ECEIVE_OK Error free data is stored in the user buffer SCI_PA RITY_ERR Parity error occurred during reception SCI_RX_DATA_EMPTY 2) No data byte is received. Required Preconditions Functions called Postconditions None No n e For single byte reception, if the byte is received, then SCIx_GetByte can be called after this function.

Input Parameter

1) These Parameters are returned in Interrupt driven mode only. 2) This Parameter is returned in case of single byte reception only, for both Polling and Interrupt driven modes.

Notes: If this function is called before any reception request is made, it will check for single byte reception, and will return SCI_RX_DATA_EMPTY until the data byte is received, and returns the reception status afterwards.

49/235

Function Descriptions

If a reception request for a set of data is over, this function will return the error status of that request only once. If this function is called again (before making next reception request), then the function will check for single byte reception. In Polling mode, this function is used in conjunction with SCIx_GetByte only. Table 25. SCIx_Forced_Clear_Flag
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions. Functions called Postconditions See also SCIx_Forced_Clear_Flag Void SCIx_Forced_Clear_Flag(void) Clears all the status and Error flags (TC, TDRE, RDRF, IDLE, OR, NF, FE, PE) in SCI Status register(SCISR). None None Transmission or Reception must have taken place. No n e None None

Note: You can call this function whenever you want to force the error and status flags be cleared. Caution: Do not call this function if a reception request is ongoing as it will corrupt the reception status by clearing all the flags and you will not receive any error status.

Table 26. SCIx_IT_Function
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions. Functions called Postconditions See also SCIx_IT_Function Void SCIx_IT_Function (void) Transmits or receives data in Interrupt driven mode. You must call this function inside the interrupt service routine. None None You must have called transmission or reception function in Interrupt driven mode. No n e Communication is started inside the interrupt subroutine. None

Note: Only use this function in the Interrupt service routine. Caution: Special care must be taken, while you write your own code along with this function in the interrupt service routine, otherwise, data transfer synchronisation could be affected, which may lead to data corruption.

50/235

Function Descriptions

Table 27. SCI2_Clkout_Enable
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions. Functions called Postconditions See also SCI2_Clkout_Enable Void SCI2_Clkout_Enable (void) This function enables the ClockOutput of SCI2 of ST72F561 device. None None No n e No n e SCI clock is availaible at a dedicated pin during communication. None

51/235

Function Descriptions

Table 28. SCI2_ClkConfigure
Function Name Function Prototype Behaviour Description SCI2_ClkConfigure Void SCI2_ClkConfigure(SCI_PO_PH_t SCI_PO_PH_Param, SCI_LBCL_t SCI_LBCL_Param) Configures the Polarity, Phase and numbers of Clock pulses for the SCI2 Clock out. SCI_PO_LOW_PH_LOW Default value on CLK pin low CLK activated at the in the middle of data bit SCI_PO_LOW_PH_HIGH Default value on CLK pin low Input Parameter 1 CLK activated at the beginning of data bit SCI_PO_HIGH_PH_LOW Default value on CLK pin High CLK activated in the middle of data bit SCI_PO_HIGH_PH_HIGH Default value on CLK pin high CLK activated at the beginning of data bit SCI_LBCL_DISABLE Input Parameter 2 The CLK pulse of last data bit is not output to the pin SCI_LBCL_ENABLE The CLK pulse of last data bit is output to the pin Output Parameters Required Preconditions. Functions called Postconditions See also None No n e No n e SCI clock is availaible at a dedicated pin during communication. None

52/235

Function Descriptions

EXAMPLE: The following C program shows how the SCI functions are used. This program runs the following sequence for an SCI without extended baudrate prescaler for polling or interrupt driven mode: transmits a single byte passed by the user transmits the 20 bytes of data at the baudrate 9600 receives 20 bytes of data at a baud rate of 9600. Note: You must define the communication mode and cpu speed (Fcpu) in the ST7lib_config.h file. You can select any of the communication speeds from the following list : SCI_POLLING_TX -- For Transmission mode S C I _ P O L L IN G _ R X -- For Reception mode SCI_ITDRV_WITHOUTBUF_TX -- For Transmission SCI_ITDRV_WITHOUTBUF_RX -- For Reception /* You can use a timeout function to handle the fault in which the control will get stuck in side a loop.This function should have the Boolean return, i.e it should return TRUE if the expected wait Time is not elapsed and FALSE if it is elapsed.*/

Software Control

Wait loop

User timeout Function

/*============================================================*/

The following variables are declared in main.h file. main.h:
#ifndef MAIN #define MAIN void Userfunction(void); BOOL User_Timeout_Function(void); void sci_rt (void); /*Declaration of user function*/

#endif /*============================================================*/

53/235

Function Descriptions

/* Program start */ #include "ST7lib_Config.h" #include "main.h" #define Buf_Size ((unsigned char)20) void main(void); static unsigned int Timeoutcount; unsigned char Buff_Rcv[20]= {"

/*List of all ST7 devices and communication mode*/ /*Declaration of all the functions used in main.c*/

"} ;

void main (void) { unsigned char Rx_Data = 0; unsigned char NbOfBytes = 20; unsigned char Tx_Data = 51; unsigned int BaudRate_Tx = 9600; unsigned int BaudRate_Rx = 9600; SCI_RxError_t Err = 0; /*user buffer*/ unsigned char Buff[Buf_Size]= "SCI DRIVERS TESTING"; unsigned char new[] = "\n\r"; BOOL Bool_Temp1 ; BOOL Bool_Temp2 ; Timeoutcount = 0; SCI_Init(SCI_DEFAULT_PARAM1, SCI_DEFAULT_PARAM2); SCI_Compute_Baudrate(BaudRate_Tx,BaudRate_Rx); /*Selects the transmission reception baudrate as 9600*/ // SCI_Extend_Baudrate (SCI_PR_13+SCI_TR_2+SCI_RR_2,0x02,0x02); /* Selects transmission reception baudrate as 9600*/ EnableInterrupts /*----------------------------------------------------------------------------Transmission through Polling mechanism -----------------------------------------------------------------------------*/ #ifdef SCI_POLLING_TX /*Selects polling mode for transmission*/ SCI_Mode(SCI_TX_ENABLE); SCI_PutByte(Tx_Data); /*Single Byte transmission*/ Bool_Temp1 = (SCI_IsTransmitCompleted()); /* this function causes a volatile variable to change,hence it cannot be put as a right side operand in a conditional stmt */ while ( (User_Timeout_Function()) && (!(Bool_Temp1))); SCI_PutBuffer( Buff,NbOfBytes); /*Continuous buffer transmission*/ #endif /*----------------------------------------------------------------------------Reception Through Polling mechanism -----------------------------------------------------------------------------*/ #ifdef SCI_POLLING_RX /*Selects polling mode for reception*/ SCI_Mode(SCI_RX_ENABLE); /* Enable the receiver mode of SCI*/ /*-----------------------------Single Byte Reception-------------------------*/ do { Err = SCI_IsReceptionCompleted(); /*Wait for data reception*/

54/235

Function Descriptions

} while ((User_Timeout_Function()) && (Err == SCI_RX_DATA_EMPTY) ); if(User_Timeout_Function()) /*Byte received before Timeout */ { if(Err == SCI_RECEIVE_OK) { Rx_Data = SCI_GetByte(); /*Correct Data Byte received*/ Nop } else { if((unsigned char)Err & SCI_NOISE_ERR) { Userfunction (); } if((unsigned char)Err & SCI_OVERRUN_ERR) { Userfunction (); } if((unsigned char)Err & SCI_FRAMING_ERR) { Userfunction (); } if((unsigned char)Err & SCI_PARITY_ERR) { Userfunction (); } /*Corrupted Data Byte received*/ Rx_Data = SCI_GetByte(); } } /*Timeout elapsed*/ else { while(1); /*Transmitter or Receiver having problem */ } /*----------------------------Buffer Reception-------------------------------*/ Err = (SCI_GetBuffer(Buff_Rcv,(unsigned char)19)); /*Reception of data in user buffer*/ if(Err == SCI_RECEIVE_OK) /*Checks the error status*/ { Nop /* Reception OK*/ } else /*Error Ocurred during reception*/ { if((unsigned char)Err & SCI_NOISE_ERR) { Userfunction (); } if((unsigned char)Err & SCI_OVERRUN_ERR) { Userfunction (); } if((unsigned char)Err & SCI_FRAMING_ERR) {

55/235

Function Descriptions

Userfunction (); } if((unsigned char)Err & SCI_PARITY_ERR) { Userfunction (); } } #endif /*----------------------------------------------------------------------------Transmission through Interrupt Driven without Buffer mode -----------------------------------------------------------------------------*/ #ifdef SCI_ITDRV_WITHOUTBUF_TX /*Selects interrupt mode for transmission*/ /*Interrupt enable when TDRE flag is set */ SCI_Mode(SCI_TX_ENABLE); if(SCI_IsTransmitCompleted()) { SCI_PutByte((unsigned char)55); while (!(SCI_IsTransmitCompleted())); SCI_PutString(Buff); /*user pointer is copied to the global pointer*/ /* Here,user can perform other tasks or operations except transmission till the time transmission is complete,after which user can perform transmission again*/ while (!(SCI_IsTransmitCompleted())); } #endif /*----------------------------------------------------------------------------Reception through Interrupt driven without Buffer mechanism -----------------------------------------------------------------------------*/ #ifdef SCI_ITDRV_WITHOUTBUF_RX /* Selects interrupt mode for transmission */ /*Interrupt enable when RDR register is ready to read*/ SCI_IT_Enable((unsigned char)SCI_RECEIVE_OVERRUN); SCI_Mode(SCI_RX_ENABLE); /*----------------------------Single Byte reception--------------------------*/ do { Err = SCI_IsReceptionCompleted(); }while ((User_Timeout_Function()) && (Err == SCI_RX_DATA_EMPTY) ); /* Wait for the completion of current data byte reception*/ if(User_Timeout_Function()) { if(Err == SCI_RECEIVE_OK) { /*Reception OK */ Nop Rx_Data = SCI_GetByte(); Nop } else { if((unsigned char)Err & SCI_NOISE_ERR) { Userfunction (); } if((unsigned char)Err & SCI_OVERRUN_ERR) {

56/235

Function Descriptions
Userfunction (); } if((unsigned char)Err & SCI_FRAMING_ERR) { Userfunction (); } if((unsigned char)Err & SCI_PARITY_ERR) { Userfunction (); } Rx_Data = SCI_GetByte(); /*User will receive the corrupted data */ } } else { while(1); } /*------------------------------Buffer Reception-----------------------------*/ SCI_GetBuffer(Buff_Rcv,(unsigned char)19); /* Any data received before calling this function is ignored*/ /* Here, user can perform other tasks or operations except reception till the time the function SCI_IsReceptionCompleted() returns RECEIVE_OK, */ after which user can perform reception again do { Err = SCI_IsReceptionCompleted(); }while (Err == SCI_BUFFER_ONGOING); /* To be sure that the communication by this point has been completed */ if(Err == SCI_RECEIVE_OK) { Nop } else { if((unsigned char)Err & SCI_NOISE_ERR) { Userfunction (); } if((unsigned char)Err & SCI_OVERRUN_ERR) { Userfunction (); } if((unsigned char)Err & SCI_FRAMING_ERR) { Userfunction (); } if((unsigned char)Err & SCI_PARITY_ERR) { Userfunction (); } } /*Transmitter or Receiver having problem */

/*Reception OK */

57/235

Function Descriptions

#endif Nop } /* * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * **** Interrupt Subroutine * * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ****/ #ifdef _HIWARE_ #pragma TRAP_PROC SAVE_REGS #else #ifdef _COSMIC_ @interrupt #else #error"Unsupported Compiler!" #endif #endif void sci_rt (void) { SCI_IT_Function(); } /* Test for HIWARE Compiler */ /* Additional registers will be saved */ /* Test for Cosmic Compiler */ /* Cosmic interrupt handling */ /* Compiler Defines not found! */

/*Interrupt function of the library*/

/* * ** * ** * ** * ** * ** * **End OF ISR* * ** * ** * ** * ** * ** * ** * **/ /*--*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-**/ void Userfunction(void) { SCI_Forced_Clear_Flag(); } BOOL User_Timeout_Function(void) { while(Timeoutcount < 50000) { Timeoutcount++ ; return (TRUE); } return (FALSE) ; }

58/235

Function Descriptions

9.1.3 SPI Following are the functions related to SPI:
Function Name Function Prototype SPI_Init Void SPI_Init ( SPI_Init_Parameter1 Init_Value1, SPI_Init_Parameter2 Init_Value2) Initialization of the SPI. By default the SPI is put in slave mode (hardware selected), baudrate Fcpu/8, the SPI peripheral is not connected to the external pins (SPE=0), alternate function of SPI output enabled (SOD=0) and interrupts are disabled. You can change the default configuration by selecting input parameters given below. You can pass one or more parameters by `OR'ing them. SPI_DEFAULT Reset Value SPI_EN ABLE Enables the serial peripheral output (SPI alternate functions connected to pins). SPI_ENABLE_IT Enables the Interrupt Selects the clock baudrate by selecting one of the below parameters. For SPI_BAUDRATE_4,Clock baudrate is Fcpu/4 Input Parameter 1 For SPI_BAUDRATE_8, Clock baudrate is Fcpu/8, (Default baudrate value) For SPI_BAUDRATE_16, Clock baudrate is Fcpu/16. For SPI_BAUDRATE_32, Clock baudrate is Fcpu/32. For SPI_BAUDRATE_64, Clock baudrate is Fcpu/64. For SPI_BAUDRATE_128, Clock baudrate is Fcpu/128. Selects the clock polarity and clock phase by selecting one of the below parameters. SPI_CLK_PP_0, For CPOL=0, CPHA =0 (Default clock polarity and phase) SPI_CLK_PP_1, For CPOL=0, CPHA =1 SPI_CLK_PP_2, For CPOL=1, CPHA =0 SPI_CLK_PP_3, For CPOL=1, CPHA =1

Behaviour Description

59/235

Function Descriptions

You can select master/ slave in hardware/ software mode by selecting one of the below parameters. SPI_MSTR_SW Selects Master in software mode Input Parameter 2 SPI_SLAVE_SW Selects Slave in software mode SPI_H W Selects hardware mode. You have to manage the SS pin accordingly for selecting Master/Slave. Output Parameters None 1. SS pin must be GND for default slave mode. 2. In hardware mode, if slave has to transmit, the SS pin of the slave has to be released and made HIGH before writing in SPIDR and reput to GND to avoid write collision error. 3. Fcpu must be defined in ST7lib_config.h. 4. SPI port pin must be configured correctly in hardware. Functions called Postconditions See also SPI_Clear_Flags If you want to enable the interrupt, the SPI_ENABLE_IT parameter has to be passed in the SPI_Init function. After the SPI_Init function is called, you should use the macro EnableInterrupts macro to reset the Interrupt mask. SPI_Output_Disable

Required Preconditions

Note: If you want to select the Interrupt driven communication mode, you must enable interrupts during initialization.

Table 29. SPI_Output_Disable
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also SPI_Output_Disable Void SPI_Output_Disable (void) Disables the alternate function of the SPI output. None None No n e None If you want to enable the SPI output again, you must call SPI_Init and pass the `SPI_DEFAULT' parameter. SPI_Init

60/235

Function Descriptions

Table 30. SPI_PutByte
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters SPI_PutByte Void SPI_PutByte (unsigned char Tx_Data) Transmits a single byte of data in SPI Polling or SPI Interrupt driven modes. Tx_Data Data byte to be transmitted. None 1. SPI should be configured correctly. 2. You must define the Transmission mode (SPI Polling or SPI Interrupt driven) Required Preconditions 3. You must enable interrupts for SPI Interrupt driven mode. 4. For SPI Interrupt driven mode, SPI_IsTransmitCompleted must have been called to ensure that there are no pending requests. 5. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Functions called Postconditions See also None Call SPI_IsTransmitCompleted after this function to get the transmission status. SPI_IsTransmitCompleted

Notes: The above function is only for SPI Polling or SPI Interrupt driven modes. It is recommended to add timeout protection when using this function. For transmission in software slave mode, you must define SPI_SLAVE_CONFIG in ST7lib_config.h.

61/235

Function Descriptions

Table 31. SPI_PutString
Function Name Function Prototype SPI_PutString SPI_TxErrCode_t SPI_PutString (const unsigned char *PtrToString) Transmits data string from the user defined address for SPI Polling mode. The data transmission will stop if any error occurs during transmission. The transmission status will be returned. *PtrToString Start address of the user string. SPI_TX_WCOL If write collision error occurs. Output Parameters SPI_TX_MODF If master mode fault occurs. SPI_TRA NSMIT_OK If there is no error in transmission. Required Preconditions Functions called Postconditions See also 1. SPI should be configured correctly. 2. You must define `SPI Polling' mode in ST7lib_config.h. None None SPI_PutString (SPI Interrupt driven mode)

Behaviour Description

Input Parameters

Notes: The above function is only for SPI Polling mode. For transmission in software slave mode, you must define SPI_SLAVE_CONFIG in ST7lib_config.h. Caution: The application can lose control if the SPI is disabled while using this function in polling mode.

62/235

Function Descriptions

Table 32. SPI_PutBuffer
Function Name Function Prototype SPI_PutBuffer SPI_TxErrCode_t SPI_PutBuffer (const unsigned char *PtrToBuffer, unsigned char NbOfBytes) Transmits data bytes from the user defined area for SPI Polling mode. The data transmission will stop if any error occurs during transmission. The transmission status will be returned. *PtrToBuffer Start address of the user buffer. NbOfBytes Number of data bytes to be transmitted. SPI_TX_WCOL If write collision error occurs. Output Parameters SPI_TX_MODF If master mode fault occurs. SPI_TRA NSMIT_OK If there is no error in transmission. 1. SPI should be configured correctly. Required Preconditions Functions called See also 2. You must define SPI Polling transmission mode in ST7lib_config.h. None SPI_PutBuffer (SPI Interrupt driven mode)

Behaviour Description

Input Parameter 1 Input Parameter 2

Notes: The above function is only for SPI Polling mode. For transmission in software slave mode, you must define SPI_SLAVE_CONFIG in ST7lib_config.h. Caution: The application can lose control if the SPI is disabled while using this function in polling mode.

63/235

Function Descriptions

Table 33. SPI_PutString
Function Name Function Prototype Behaviour Description SPI_PutString Void SPI_PutString (const unsigned char *PtrToString) Starts transmission of data string in the interrupt service routine, from the user defined area for SPI Interrupt driven mode. *PtrToString Start address of the user string. None 1. The SPI should be configured correctly. 2. You must define SPI Interrupt driven mode in ST7lib_config.h. 3. You must enable interrupts for this mode. 4. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Functions called Postconditions See also None SPI_IsTransmitCompleted can be called after this function to get the transmission status. SPI_IsTransmitCompleted, SPI_PutString (SPI Polling mode)

Input Parameters Output Parameters

Required Preconditions

Notes: The above function is only for SPI Interrupt driven mode. For software slave mode transmission, you must define SPI_SLAVE_CONFIG in ST7lib_config.h. Caution: Do not access the string until transmission is completed Data transmission will stop if any error occurs during transmission.

64/235

Function Descriptions

Table 34. SPI_PutBuffer
Function Name Function Prototype Behaviour Description Input Parameter 1 Input Parameter 2 Output Parameters SPI_PutBuffer Void SPI_PutBuffer (const unsigned char *PtrToBuffer, unsigned char NbOfBytes) Starts transmission of data in the interrupt service routine, from the user defined area for SPI Interrupt driven mode. *PtrToBuffer Start address of the user buffer. NbOfBytes Number of data bytes to be transmitted. None 1. The SPI should be configured correctly. 2. You must define the transmission mode as SPI Interrupt driven in ST7lib_config.h. 3. You must enable interrupts for this mode. 4. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Postconditions See also You can call `SPI_IsTransmitCompleted' after this function to get the transmission status. SPI_IsTransmitCompleted, SPI_PutBuffer (SPI Polling mode)

Required Preconditions

Notes: The above function is only for SPI Interrupt driven mode. For transmission in software slave mode, you must define SPI_SLAVE_CONFIG in ST7lib_config.h. Caution: Do not access the string until transmission is completed. Data transmission will stop if any error occurs during transmission.

65/235

Function Descriptions

Table 35. SPI_IsTransmitCompleted
Function Name Function Prototype Behaviour Description Input Parameters SPI_IsTransmitCompleted SPI_TxErrCode_t SPI_IsTransmitCompleted (void) Checks for errors, checks for pending requests and returns the transmission status. None SPI_TX_WCOL If write collision error occurs. SPI_TX_MODF If master mode fault occurs. SPI_TRA NSMIT_OK Output Parameters If there is no error in transmission and all data bytes are transmitted. SPI_TX_BUFFER_ONGOING 1) If all the data bytes from user buffer are not transmitted. SPI_TX_STRING_ONGOING 1) If the complete string is not transmitted. Required Preconditions Functions called Postconditions See also None None None None

1) These Parameters are returned in SPI Interrupt driven mode only.

Notes: The above function is for SPI Polling and SPI Interrupt driven modes. In `SPI Polling' mode, this function is called only after SPI_PutByte function.

66/235

Function Descriptions

Table 36. SPI_GetByte
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters SPI_GetByte Unsigned char SPI_GetByte (void) Returns the most recent Byte received in SPI Polling or SPI Interrupt driven mode. None Unsigned char Returns the received data byte. 1. The SPI should be configured correctly. 2. You must define SPI Polling or SPI Interrupt driven mode in ST7lib_config.h. 3. You must enable interrupts for SPI Interrupt driven mode. Required Preconditions 4. In both SPI Polling and SPI Interrupt driven modes you must call SPI_IsReceptionCompleted before this function to check the reception status. 5. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Functions called Postconditions See also None None SPI_IsReceptionCompleted

Notes: The above function is for SPI Polling or SPI Interrupt driven mode. It is recommended to add a timeout protection when using this function.

67/235

Function Descriptions

Table 37. SPI_GetString
Function Name Function Prototype SPI_GetString SPI_RxErrCode_t SPI_GetString (unsigned char *PtrToString) Receives the data string in SPI Polling mode and stores it in a user defined area. The data reception will stop if any error occurs during reception. The reception status will be returned. *PtrToString Start address of the String SPI_RX_MODF If master mode fault occurs. Output Parameters SPI_RX_OVR If overrun condition occurs. S P I _ R E CE I V E _ O K If there is no error in reception. Required Preconditions Functions called Postconditions See also 1. The SPI must be configured correctly. 2. You must define SPI Polling mode in ST7lib_config.h. None None SPI_GetString (SPI Interrupt driven mode)

Behaviour Description

Input Parameters

Note: The above function is only for SPI Polling mode. Caution: The application can lose control if the SPI is disabled while using this function in polling mode.

68/235

Function Descriptions

Table 38. SPI_GetBuffer
Function Name Function Prototype SPI_GetBuffer SPI_RxErrCode_t SPI_GetBuffer (unsigned char *PtrToBuffer, unsigned char NbOfBytes) Receives a number of data bytes in SPI Polling mode and stores them in a user defined area. The data reception will stop if any error occurs during reception. The reception status will be returned. *PtrToBuffer Start address of the user buffer. NbOfBytes Number of bytes to be received. SPI_RX_MODF If master mode fault occurs. Output Parameters SPI_RX_OVR If overrun condition occurs. S P I _ R E CE I V E _ O K If there is no error in reception. Required Preconditions Functions called See also 1. The SPI should be configured correctly. 2. You must define SPI Polling mode in ST7lib_config.h. None SPI_GetBuffer (SPI Interrupt driven mode)

Behaviour Description

Input Parameter 1 Input Parameter 2

Note: The above function is only for SPI Polling mode. Caution: The application can lose control if the SPI is disabled while using this function in polling mode.

69/235

Function Descriptions

Table 39. SPI_GetString
Function Name Function Prototype Behaviour Description SPI_GetString Void SPI_GetString (unsigned char *PtrToString) Starts reception of a data string in SPI Interrupt driven mode in the interrupt service routine and stores it in a user defined area. *PtrToString Input Parameters Output Parameters Start address of the location where the string is to be placed. None 1. The SPI should be configured correctly. 2. You must define SPI Interrupt driven reception mode in ST7lib_config.h. 3. You must enable interrupts for this mode. 4. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Functions called Postconditions See also None You must call SPI_IsReceptionCompleted after this, to check the reception status. SPI_IsReceptionCompleted, SPI_GetString (SPI Polling mode)

Required Preconditions

Note: The above function is only for SPI Interrupt driven mode. Caution: Take care not to access the string until reception is complete. Any data received before calling this function is ignored. The data reception will stop if any error occurs during reception.

70/235

Function Descriptions

Table 40. SPI_GetBuffer
Function Name Function Prototype Behaviour Description SPI_GetBuffer Void SPI_GetBuffer (unsigned char *PtrToBuffer, unsigned char NbOfBytes) Starts reception of data in the interrupt service routine and stores it in user defined area for SPI Interrupt driven mode. *PtrToBuffer Start address of the user buffer. NbOfBytes Number of bytes to be received. None 1. The SPI should be configured correctly. 2. You must define the SPI Interrupt driven reception mode in ST7lib_config.h. 3. You must enable interrupts for this mode. 4. For SPI Interrupt driven mode, SPI_IT_Function must have been called in the Interrupt service routine. Functions called Postconditions See also None You must call SPI_IsReceptionCompleted after this to check the reception status. SPI_IsReceptionCompleted, SPI_GetBuffer (SPI Polling mode)

Input Parameter 1 Input Parameter 2 Output Parameters

Required Preconditions

Note: The above function is only for SPI Interrupt driven mode. Caution: Take care not to access the string until reception is complete. Any data received before calling this function is ignored The data reception will stop if any error occurs during reception.

71/235

Function Descriptions

Table 41. SPI_IsReceptionCompleted
Function Name Function Prototype SPI_IsReceptionCompleted SPI_RxErrCode_t SPI_IsReceptionCompleted (void) For reception of a set of data in SPI Interrupt driven mode, this function checks for the completion of the reception or the occurrence of an error and returns the reception status. Behaviour Description For reception of single byte of data in either SPI Polling or SPI Interrupt driven mode, it checks if a data byte has been received and is ready for processing. It returns SPI_RX_DATA_EMPTY until the data byte is received and returns the reception status afterwards. None SPI_RX_MODF If master mode fault occurs. SPI_RX_OVR If overrun condition occurs. SPI_RE CEIVE _OK If the reception is completed without any error. SPI_RX_BUFFER_ONGOING 1) If the buffer is not full. SPI_RX_STRING_ONGOING 1) If the complete string is not received in the user buffer. SPI_RX_DATA_EMPTY 2) If no data byte is received. Required Preconditions Functions called Postconditions See also None None 1.For single byte reception, if the byte is received, then SPI_GetByte can be called after this function. 2.SPI_Clear_Flags can be called to clear the error and status flags, if required. None

Input Parameters

Output Parameters

1) These Parameters are returned in SPI Interrupt driven mode only. 2) This Parameter is returned in case of single byte reception only, for both SPI Polling and SPI Interrupt driven modes.

Notes: In SPI Polling mode, this function is used in conjunction with SPI_GetByte only. If this function is called before any reception request is made, it will check for single byte reception, and will return SPI_RX_DATA_EMPTY until the first data byte is received, and returns the reception status when reception is complete. If a reception request is over, this function will return the error status of that request only once. If this function is called again (before making next reception request), then the function will check for single byte reception.

72/235

Function Descriptions

Table 42. SPI_IT_Function
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also SPI_IT_Function Void SPI_IT_Function (void) Transmits or receives data in SPI Interrupt driven mode. You must call this function in the interrupt service routine. None None You must have called transmission or reception function in SPI Interrupt driven mode before this. None None None

Note: You must use this function only in the Interrupt service routine. Caution: Special care must be taken, while you write your own code along with this function inside the interrupt service routine. Otherwise, data transfer synchronisation will be affected, which may lead to data loss or overrun error.

Table 43. SPI_Clear_Flags
Function Name Function Prototype Behaviour Description Input Parameters Output Parameters Required Preconditions Functions called Postconditions See also SPI_Clear_Flags Void SPI_Clear_Flags (void) Clears the SPI error (WCOL, MODF and OVR bits of SPICSR register) and status (SPIF bit of SPICSR) flags. None None Transmission or Reception must have taken place. None None SPI_IsTransmitCompleted SPI_IsReceptionCompleted

Note: You can call this function whenever you want to force the error and status flags to be cleared. Caution: Do not call this function if a reception request is ongoing as it will corrupt the reception status by clearing all the flags and you will not receive any error status. .

73/235

Function Descriptions

EXAMPLE: The following C program shows the use of SPI functions. Program Description: This program runs the following sequence for the SPI for SPI Polling and SPI Interrupt driven modes: 1. Transmits a single byte passed by the user and receives single byte of data, 2. Transmits and receives the 10 bytes of data, You can select one pair of the following communication modes, for transmission and reception respectively: SPI_POLLING_TX -- For Transmission mode SPI_POLLING_RX -- For Reception mode SPI_ITDRV_WITHOUTBUF_TX - For Transmission mode SPI_ITDRV_WITHOUTBUF_RX -- For Reception mode
/* User can use a time out function to handle the fault in which the control will get stuck in side a loop.This function should have the Boolean return, i.e it should return TRUE if the expected wait Time is not elapsed and FALSE if it is elapsed.*/

Software Control

Wait loop

User defined time out function

/*============================================================*/

The following variables are declared in main.h file. main.h:
#ifndef MAIN #define MAIN BOOL User_Timeout_Function(void) ; void User_Function(void); void SPI_User_IT_Routine (void);//newly added /* Prototypes of user function */

/* Declaration of all global variables used in main.c */ #define buf_size 0x0A #define My_Data (unsigned char)0x55 static unsigned int Timeoutcount; #endif /*============================================================*/

74/235

Function Descriptions

/* Program Start */ #include "ST7lib_config.h" /*List of all ST7 devices and communication mode */ #include "main.h" /* Declaration of prototypes of user defined functions used in main.c */ void main(void); void main(void) { unsigned char NbOfBytes_get = 10; unsigned char NbOfBytes_put = 10; unsigned char Rx_Data; unsigned char Buff_Test[buf_size]; unsigned char Buff[buf_size] ={0x00,0x55,0xAA,0xFF,0x00,0x55,0xAA,0xFF,0x00,0x55}; SPI_TxErrCode_t Temp1= 0x00 ; SPI_RxErrCode_t Temp2= 0x00 ; SPI_Init((((unsigned char)SPI_DEFAULT | ((unsigned char)SPI_ENABLE| ((unsigned char)SPI_ENABLE_IT|((unsigned char)SPI_BAUDRATE_4| ((unsigned char)SPI_CLK_PP_0)))))), SPI_MSTR_SW ); /* SPI Initialised in master software mode,Serial peripheral output enabled, Interrupt enabled, CPOL=0, CPHA=1 and baudrate is 2MHz */ EnableInterrupts /* Interrupt mask is reset for enabling interrupt */ /*========================================================================= Transmission through `Polling' mode =========================================================================*/ #ifdef SPI_POLLING_TX /* Single byte data transmission */ SPI_PutByte (My_Data) ; Temp1 = SPI_IsTransmitCompleted(); while ((!(User_Timeout_Function())) && (Temp1 != SPI_TRANSMIT_OK) ) { Temp1 = SPI_IsTransmitCompleted() ; } if (!(User_Timeout_Function())) { switch (Temp1) { case (SPI_TX_MODF + SPI_TX_WCOL): case (SPI_TX_MODF): case (SPI_TX_WCOL): User_Function(); /* Error Management */ break; default: /* If none of the above condition is met */ User_Function(); break; } } /* Transmission of 10 data bytes from user buffer */ switch(SPI_PutBuffer(Buff, (unsigned char)10)) { case (SPI_TX_MODF + SPI_TX_WCOL):

75/235

Function Descriptions

case (SPI_TX_MODF): case (SPI_TX_WCOL): User_Function(); break; case SPI_TRANSMIT_OK: break; default: User_Function(); break;

/* Error Management */ /*Transmission is successful */ /* If none of the above condition is met */

} #endif /*========================================================================= Reception through `Polling' mode =========================================================================*/ #ifdef SPI_POLLING_RX /* Single byte data reception Temp2 = SPI_IsReceptionCompleted() ; while ((User_Timeout_Function()) && (Temp2 == SPI_RX_DATA_EMPTY)) /* Waits for data byte reception { Temp2 = SPI_IsReceptionCompleted() ; } /* Waiting for data byte reception if (User_Timeout_Function()) { switch (Temp2) { case (SPI_RX_MODF + SPI_RX_OVR): case (SPI_RX_MODF): case (SPI_RX_OVR): User_Function(); /* Error Management Rx_Data = SPI_GetByte () ; /* Corrupted data byte received break; case SPI_RECEIVE_OK: /* Reception successful Rx_Data = SPI_GetByte () ; break; default: /* If none of the above condition is met User_Function(); break; } } else { while (1) ; /* Handle time out as Transmitter/Receiver is having some problem */ } /* Reception of set of data switch ((SPI_GetBuffer(Buff_Test,(unsigned char)10))) { case (SPI_RX_MODF + SPI_RX_OVR): case (SPI_RX_MODF): case (SPI_RX_OVR): User_Function(); /* Error Management break; case SPI_RECEIVE_OK: /* Reception is successful break;

*/

*/

*/

*/ */ */

*/

*/

*/ */

76/235

Function Descriptions

default: User_Function(); break;

/* If none of the above condition is met */

} #endif /*========================================================================= Transmission through 'Interrupt Driven wihtout Buffer Mode' =========================================================================*/ #ifdef SPI_ITDRV_WITHOUTBUF_TX /* Single byte transmission */ SPI_PutByte (My_Data) ; /* Here, user can perform other tasks or operations except transmission till the time transmission is complete, after which user can perform transmission again */ Temp1 = SPI_IsTransmitCompleted() ; while((Temp1 == SPI_TX_BUFFER_ONGOING) && (Temp1 == SPI_TX_STRING_ONGOING)) /* Wait for transmission completion { Temp1 = SPI_IsTransmitCompleted() ; } switch (Temp1) { case (SPI_TX_MODF + SPI_TX_WCOL): case (SPI_TX_MODF): case (SPI_TX_WCOL): User_Function(); /* Error Management break; /* Transmission is successful case SPI_TRANSMIT_OK: break; default: /* If none of the above condition is met User_Function(); break; } /* Transmission of 10 data bytes from user buffer /* User pointer is copied to the global pointer SPI_PutBuffer(Buff, NbOfBytes_put); /* Here, user can perform other tasks or operations except transmission till the time transmission is complete, after which user can perform transmission again */ Temp1 = SPI_IsTransmitCompleted() ; while ((User_Timeout_Function())&&(Temp1 == SPI_TX_BUFFER_ONGOING)) { Temp1 = SPI_IsTransmitCompleted() ; } /* To be sure that the communication by this point has been completed */ if (User_Timeout_Function()) { switch (Temp1) { case (SPI_TX_MODF + SPI_TX_WCOL): case (SPI_TX_MODF): case (SPI_TX_WCOL):

*/

*/ */ */

*/ */

77/235

Function Descriptions

User_Function(); break; case SPI_TRANSMIT_OK: break; default: User_Function(); break; } } else { while (1) ;

/* Error Management */ /* Transmission successful */ /* If none of the above condition is met */

/* Time-Out elapsed without transmission completion. Error in communication and user should handle the case */ } #endif /*========================================================================= Reception through 'Interrupt Driven wihtout Buffer Mode' ======================