ST UM0151 User Manual

UM0151

User Manual

STVP programming toolkit

Introduction

The STVP programming toolkit provides a set of C++ source and header files that can be
used to design a customized programming application for any ST programming hardware
that is supported by STVP.

The provided files contain the source code for functions that allow your programmin g
application to access STVP’s low level DLLs.

With access to these STVP DLLs, you can program ST7, STM8 and STM32
microcontrollers using any supported programming hardware (ST7-STICK, ST socket
boards, EPB, DVP3, EMU3, STice, ST-LINK, ST-TSLINK and Raisonance STX-RLINK) and
programming methods (socket, in-circuit or in-situ programming).

Figure 1.

Programming application schematic

Your programming application

Programming toolkit

- PtkApi.ccp

- PtkToolBox.ccp

Programming DLLs (from STVP)

Configuration files (from STVP)

1. ST7 Flash STICK: In-circuit progra mmi n g (ICP )

2. DVP3 series emulator: In-circuit programming (ICP)

3. EMU3 series emulator with ICC Add-on (ICP)

4. ST7SB socket board: Programming sockets for all ICP capable hardware

5. EPB series programmer:

- Programming sockets

- ICP depending on version and target ST microcontroller

6. STice advanced emulation system (ICP)

7. ST-LINK in-circuit debugger/programmer (ICP)

8. STX-RLink in-circuit debugger/programmer (ICP)

9. ST-TSLINK programming dongle (ICP)

Note: Creating a programming application with the STVP programming toolkit requires the

installation of ST Visual Programmer version 1.9.1 or later.

June 2011 Doc ID 11472 Rev 5 1/29

www.st.com

Contents UM0151

Contents

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1 About the user manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Getting assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Programming toolkit contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Understanding the STVP DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Designing a custom programming application . . . . . . . . . . . . . . . . . . . 7

4.1 Setting up the DLL environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.2 Configuring the device and the programming hardware . . . . . . . . . . . . . . . 8

4.3 Accessing the memory image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.3.1 Loading a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.3.2 Writing in the memory image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.4 Connecting to the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.4.1 Blank checking the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.4.2 Programming the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.4.3 Verifying the programming of the device . . . . . . . . . . . . . . . . . . . . . . . . 11

4.4.4 Reading the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 DLL supported functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.1 DLL environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.2 Hardware and device configuration functions . . . . . . . . . . . . . . . . . . . . . . 16

5.3 Image area access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.4 Device connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Programming toolkit helper functions . . . . . . . . . . . . . . . . . . . . . . . . . 22

Appendix A Product support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

7 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2/29 Doc ID 11472 Rev 5

UM0151 Overview

1 Overview

1.1 About the user manuals

This manual provides information and examples to help you develop your programming
application with the programming toolkit. It describes:

● The functions supported by the STVP DLLs

● Using the functions provided by the programming toolkit

For information about STVP and supported ST programming hardware, you can refer to the
following:

● ST Visual Programmer on-line help, information about STVP and supported hardware

and programming methods

● ST Visual Programmer Release Notes, co mplete r elease information about the current

release of STVP, including supported programming hardware and ST microcontrollers

For information about setup and connection information for supported programming
hardware, you can refer to the following:

● ST7-STICK User Manual

● ST7SB Socket Board User Manual

● ST7-EPB User Manual

● ST7-D VP3 Emulator User Manual

● ST7-EMU3 Emulator User Manual

●

STice User Manual

●

ST-LINK User Manual

●

ST-TSLINK User Manual

● Raisonance STX-RLINK User Manual (on the Raisonance web site)

For progr amming information that is specific to your ST microcontroller, refer to the relevant
datasheet.

1.2 Getting assistance

For more information, application notes, FAQs and software updates on all the ST
microcontroller families, check out the CD-ROM or our website: www.st.com

For assistance on all ST microcontroller subjec ts, or f or help using y our emulator , r efer to the
contact list provided in the Chapter Appendix A: Product support. We’ll be glad to help you.

Doc ID 11472 Rev 5 3/29

Programming toolkit contents UM0151

2 Programming toolkit contents

The programming toolkit is a set of C++ source and header files that you integrate into your
application in order to use the programming functions supported by STVP’s DLLs. In
addition, the toolkit contains two samples that demonstrate the types of applications that
can be created.

When you run the auto ex tracting zip, the programming toolkit files and this documentation
are placed in the directory that you specified on your PC. These files and folders include:

Table 1. Installed components: programmin g toolkit source and header files

Contains the C++ source files that you include in your application in order to

src:

access the functions of the STVP DLLs.

PtkApi.cpp:

Source and header that enable the importation of functions from the
application programming interfaces (API) of the STVP DLLs.

PtkApi.h:

Source and header for “Helper Functions” for tasks such as retrieving

PtkToolBox.cpp
PtkToolBox.cpp

configuration files or accessing the “memory image.” The Helper
Functions should always be used to access the configuration
information as the format and content of these databases may
change without notification when STVP is upgraded. Even if the
format of the database changes, the prototypes for the Helper
Functions will remain the same.

Note: The source files provided in the programming toolkit are in C++ format (.cpp), however they

can be compiled as C source files. Developing your application using another programming
language does not necessarily pose a compatibility problem with the STVP DLLs, however
these developers will have to rewrite the application programming interface (PtkApi.cpp).

Programming applications created using the programming toolkit rely on STVP’s DLLs and
configuration files (see the cover page). The programming toolkit does not contain thes e
files; they are installed with STVP. These files must then be placed in the same directory as
your programming ap plication. More information about these DLLs is prov ided in the next
chapter, Understanding the STVP DLLs.

Note: Both the STVP programming toolkit and the latest version of ST Visual Programmer can

be downloaded for free from www.st.com/mcu.

4/29 Doc ID 11472 Rev 5

UM0151 Programming toolkit contents

Table 2. Source files and executables for two sample applications:

The samples, APISample.exe and MFCSample.exe , are C applications de veloped

Sample:

ApiSample:

with Visual C++ 6.0. They should be executed from the directory where you have
installed STVP version 1.9.1 or later.

Contains the C++ source and header files for a console application
that is intended to illustrate:

• How to set the hardware and MCU configuration: ST-LINK, USB,
STM8L15xC6, SWIM protocol

• How to load binary files in "PROGRAM MEMORY" and in "OPTION
BYTE" areas

• How to program and verify the "PROGRAM MEMORY"

• How to program and verify the "OPTION BYTE"
This sample can easily be rebuilt in an environment other than

Visual C++ 6.0.

Readme.txt

Distrib:

MFCSample:

Readme.txt:

Distrib:

Provides details about the use of the ApiSample application.

This subdirectory contains the executable and .hex files for the
ApiSample. The files include:

The executable for the application programming

ApiSample.exe:

interface. This ex ecutable should be ex ecuted from
the directory where you have installed STVP.

Dummy application code that the sample

option.hex:

application programs to the option byte area of the
ST microcontroller’s memory.

Dummy application code that the sample

progmem.hex:

application programs to the ST microcontroller’s
Program Memory area.

Contains the C++ source and header files for an application that
uses the Microsoft Foundation Classes. In addition to the features
demonstrated in ApiSample, MFCSample specifically illustrates the
use of the helper functions to access and configure data.

Provides details about the use of the MFCSample application.

This subdirectory contains the MFCSample executable file.

res:

MFCSample.ex
e:

The executable for the application programming
interface. This ex ecutable should be ex ecuted from
the directory where you have installed STVP.

Contains the resource files for the graphical interface, which were
used to build the sample application.

Doc ID 11472 Rev 5 5/29

Understanding the STVP DLLs UM0151

3 Understanding the STVP DLLs

Because your programming application must use the STVP DLLs, you should first
understand their roles. The software elements that your application accesses and their
relationships are shown in Figure 2. These elements include:

Table 3. STVP DLLs and configuration files

Configuration files

DBCFILE.CNF Contain a database of information on all STVP supported devices (memory mappings, option

TOOLS.CNF

DLLs

DBCA60.DLL

bytes, protocols) and programming hardware configurations (supported devices, protocols,
communication ports). Typically, these files evolve with new releases of STVP. However, if you
use the programming toolkit, these evolutions should not pose a problem for your application.

Database configuration access. Used by HAPL, EPRCORE60 and programming toolkit to
get lists of devices, programming hardware and other hardware and de vice information from the
configuration files.

EPRCORE60.DLL

FILE60.DLL

HAPL.DLL

LEF60.DLL

Epromer core. Keeps track of the device description and creates the programming interface
between the GUI and the appropriate HAPL.

A component DLL of the EPRCORE60 layer . It ensures loading and sa ving of the de vice binary
files. Supported formats include Motorola (.S19) and Intel (.HEX).

Hardware programming level. Hardware specific DLLs that are in charge of programming a
specific type of device using a specific type of hardware. The EPRCORE60 loads the
appropriate HAPL for the hardware and device configuration.

Logging / Error features . Ensures the propagation of errors between the different layers. It
may also log execution traces.

Figure 2. STVP DLLs and configuration files

6/29 Doc ID 11472 Rev 5

UM0151 Designing a custom programming application

4 Designing a custom programming application

For the purposes of understand ing th e di f ferent functions suppo rted by the STVP DLL s, the
programming process can be divided into four categories of functions:

● Setting up the DLL environment

● Configuring the device and the programming hardware

● Accessing the memory image

● Connecting to the device

The following sections provide coded examples to show how an application might use the
different functions in each category to accomplish specific programming tasks.

Before getting started, it is also important to recognize that your application can be

dynamic, offering as much control of hardware configuration and options as STVP, or
static, with the hardware configuration hard-coded into the programming application. The

programming toolkit provides Helper Functions that allow you to return lists of devices,
hardware and protocols at run time so that they can be used by your application (refer to

Programming toolkit helper functions). Howev er, for simplicity, the examples provided in the

following section are for a static interface with the configuration hard-coded into the
application.

4.1 Setting up the DLL environment

The STVP DLLs described in Section 3 must be initialized by your application and the
callback functions that allow it to manage errors, messages and process execution must
also be initialized.

The following is a standar d initialization that you might use in your application.
long CALLBACK AppendMessageText( const char* szMsg)

{

.....

}
long CALLBACK AppendErrorText( const char* szMsg)
{

.....

}
long CALLBACK AppendWarningText( const char* szMsg)
{

.....

}
long CALLBACK UpdateProgress( int percentage* szMsg)
{

.....

}

Note: The CALLBACK notation used here is standard when using Microsoft Visual Studio C++.

However, for other development environments, you may have to use a different notation.

InitDLLCallBack()
{

Doc ID 11472 Rev 5 7/29

Designing a custom programming application UM0151

LSetErrorCallBack( AppendErrorText);
LSetWarningCallBack( AppendWarningText);
LSetMessageCallBack( AppendMessageText);

LSetProgressCallBack( UpdateProgress);
}
main() {
// Load DLLs and Initialize the address of API
// functions
if (LoadDlls(“C:\my_installation\STVP\”)==1) {

InitDLLCallBack();

.....

// Log everything

LOpenLog( “Activity.log”);

.....

SetProgrammingConfiguration();

DoesProgrammingJob();

.....

LCloseLog();

Clean();

}
}

4.2 Configuring the device and the programming hardware

The STVP DLLs support numerous hardware configurations and target devices. Correct
identification of the programming hardware is important in establishing the necessary
hardware connections, as well as programming and verification of the target device. Once
the configuration is set, the correct HAPL.DLL is load ed to m anage communication with the
device.

Based on the device selected for programming, the programming software also creates
buffer area in your PCs RAM for the data that will be programmed to the device. This buffer
is called the Memory Image. It is also used as a model to check against when verifying the
programming of the device.

The routine below is initiated by the SetProgrammingConfiguration() function. This is an
example of a static interface where the following configuration is hard-coded into the
application:

Hardware: ST-LINK
Protocol: SWIM
Device: STM8L15xC6
Port: USB

Note: This example is incomplete as some parts of the code are implementation-driven.

BOOL SetProgrammingConfiguration()
{
// Select the hardware in this case ST-LINK with
// “SWIM”
// protocol, FALSE means that we are not using
// simulation mode
if (ESelectHard(“ST-LINK”, “SWIM” ,FALSE)==0)

8/29 Doc ID 11472 Rev 5

UM0151 Designing a custom programming application

{

return false;

}
// Prevent from opening a warning dialog box when
// Option byte protection bit is to be programmed.
// By default, the Protection warning dialog box is
// opened
if (ESetPreferences (PROTECTION_WARNING, FALSE)==0}

{

return false;

}
// Select the device : STM8L15xC6 device
if (ESelectDevice(“STM8L15xC6”)==0))

{

return false;

}
if (ESelectPort (“USB”)==0))

{

return false;

}

return true;
}

4.3 Accessing the memory image

Once the programming hardware, the device and the port have been specified, the
EPRCORE60.DLL allocates memory structures and buffer s for each memory area
supported by the device (PROGRAM, DATA, OPTION). The memory buffer internally
allocated by EPRCORE60 is called the Memory Image. A unique internal identifier is giv en
to each area. This identifier should be used later in t he API fu nctions when ever you need to
identify a specific memory area.

With the Memory Image established, the programing applicat ion can no w access th is b uf fer
and load the binary file (.HEX or .S19) that you wish to program to your device, as well as
writing any information that is specific to the programming of each device (ex. a product
serial number).

Caution: If your software reads y our ST microcontroller ’ s memory, the data from the de vice ov erwrites

any data that is already stored in the Memory Image.

4.3.1 Loading a file

In the following example the specified binary file (MyAppli.S19), which is to be programmed
to the target device, is retrieved and saved to the Memory Image. This file is located and
saved by the FILE60 component of the EPRCORE60.

// Search the PROGRAM MEMORY ID
unsigned long iAreaId
if (EGetId("PROGRAM MEMORY", &iAreaId) == 1)

{

// Load the file MyAppl.S19 in the program memory area

iReturn = ELoadFile(“MyAppl.S19”,iAreaId);

}

Doc ID 11472 Rev 5 9/29