STMicroelectronics STVP programming toolkit User Manual
Reklama
Reklama
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 programming 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 programming (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.
March 2012 Doc ID 11472 Rev 6 1/30 www.st.com
Contents
Contents
UM0151
Programming toolkit contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Understanding the STVP DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Designing a custom programming application . . . . . . . . . . . . . . . . . . . 7
Setting up the DLL environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Configuring the device and the programming hardware . . . . . . . . . . . . . . . 8
Accessing the memory image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Writing in the memory image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Blank checking the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Programming the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Verifying the programming of the device . . . . . . . . . . . . . . . . . . . . . . . . 11
DLL supported functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
DLL environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Hardware and device configuration functions . . . . . . . . . . . . . . . . . . . . . . 17
Image area access functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Device connection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6 Programming toolkit helper functions . . . . . . . . . . . . . . . . . . . . . . . . . 23
2/30 Doc ID 11472 Rev 6
UM0151
1 Overview
1.1
Overview
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 , complete release 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
ST-LINK User Manual
ST-TSLINK User Manual
ST7SB Socket Board User Manual
ST7-EPB User Manual
ST7-DVP3 Emulator User Manual
ST7-EMU3 Emulator User Manual
STice User Manual
Raisonance STX-RLINK User Manual (on the Raisonance web site)
For programming information that is specific to your ST microcontroller, refer to the relevant datasheet .
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 subjects, or for help using your emulator, refer to the
contact list provided in the Chapter Appendix A: Product support
. We’ll be glad to help you.
Doc ID 11472 Rev 6 3/30
Programming toolkit contents
2 Programming toolkit contents
Note:
Note:
UM0151
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 extracting 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.
src:
Installed components: programming toolkit source and header files
Contains the C++ source files that you include in your application in order to access the functions of the STVP DLLs.
PtkApi.cpp:
PtkApi.h:
Source and header that enable the importation of functions from the application programming interfaces (API) of the STVP DLLs.
PtkToolBox.cpp
PtkToolBox.cpp
Source and header for “Helper Functions” for tasks such as retrieving 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.
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 these files; they are installed with STVP. These files must then be placed in the same directory as your programming application. More information about these DLLs is provided in the next chapter,
Both the STVP programming toolkit and the latest version of ST Visual Programmer can be downloaded for free from www.st.com/mcu .
4/30 Doc ID 11472 Rev 6
UM0151 Programming toolkit contents
Table 2.
Sample:
Source files and executables for two sample applications:
The samples, STVP_CmdLine.exe and MFCSample.exe, are C applications developed with
Visual C++ 6.0. They should be executed from the directory where you have installed STVP version 1.9.1 or later.
ApiSample:
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
Provides details about the use of the STVP_CmdLine application.
Release:
MFCSample:
This subdirectory contains the executable and .hex files for the STVP_CmdLine.
The files include:
STVP_CmdLine.exe: progmem.hex:
The executable for the application programming interface. This executable should be executed from the directory where you have installed STVP.
Dummy application code that the sample application programs to the ST microcontroller’s Program
Memory area.
option.hex:
Dummy application code that the sample application programs to the option byte area of the ST microcontroller’s memory.
Contains the C++ source and header files for an application that uses the
Microsoft Foundation Classes. In addition to the features demonstrated in
STVP_CmdLine, MFCSample specifically illustrates the use of the helper functions to access and configure data.
Readme.txt:
Provides details about the use of the MFCSample application.
This subdirectory contains the MFCSample executable file.
Release: res:
MFCSample.exe:
The executable for the application programming interface. This executable should be executed 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 6 5/30
Understanding the STVP DLLs
3 Understanding the STVP DLLs
UM0151
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
TOOLS.CNF
Contain a database of information on all STVP supported devices (memory mappings, option 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.
DLLs
DBCA60.DLL
Database configuration access . Used by HAPL, EPRCORE60 and programming toolkit to get lists of devices, programming hardware and other hardware and device information from the configuration files.
EPRCORE60.DLL
Epromer core . Keeps track of the device description and creates the programming interface between the GUI and the appropriate HAPL.
FILE60.DLL
HAPL.DLL
LEF60.DLL
A component DLL of the EPRCORE60 layer. It ensures loading and saving of the device 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/30 Doc ID 11472 Rev 6
UM0151
4
Designing a custom programming application
Designing a custom programming application
●
●
●
●
For the purposes of understanding the different functions supported by the STVP DLLs, the programming process can be divided into four categories of functions:
Setting up the DLL environment
Configuring the device and the programming hardware
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 ). However, for simplicity, the examples provided in the
following section are for a static interface with the configuration hard-coded into the application.
4.1
Note:
Setting up the DLL environment
The STVP DLLs described in
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 standard 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)
{
.....
}
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 6 7/30
Designing a custom programming application
{
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
Note:
UM0151
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 loaded to manage 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
This example is incomplete as some parts of the code are implementation-driven.
BOOL SetProgrammingConfiguration()
{
// Select the hardware in this case ST-LINK with
8/30 Doc ID 11472 Rev 6
UM0151 Designing a custom programming application
// “SWIM”
// protocol, FALSE means that we are not using
// simulation mode if ( ESelectHard (“ST-LINK”, “SWIM” ,FALSE)==0)
{ 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 buffers 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 given to each area. This identifier should be used later in the API functions whenever you need to identify a specific memory area.
With the Memory Image established, the programing application can now access this buffer 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 your ST microcontroller’s memory, the data from the device overwrites any data that is already stored in the Memory Image.
Doc ID 11472 Rev 6 9/30
Designing a custom programming application UM0151
4.3.2
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);
}
Writing in the memory image
You can also write punctually to specific memory locations as shown in this example. In the sample provided the data is an integer that is incremented each time a device is programmed. For example, this value could be a product serial number or other identification.
.....
// Write 1,2,3,4 in memory image at location 0x2000 for (i=1;i<=4;i++)
{
SetByteInImageMemory (STM8L15xC6, "PROGRAM MEMORY",0x2000+i- 1,i);
}
.....
4.4
4.4.1
Connecting to the device
The following examples use the functions that interact with the device that is to be programmed. At this stage your programming application is writing to the device’s memory, the data which has been stored in the Memory Image. This section provides examples specifically for blank checking, programming, verifying and reading a device.
Blank checking the device
Blank checking the device’s memory allows you to confirm that the device has not already been programmed. Some devices do not support blank check. To avoid an error when not supported, you can use the IsBlankCheckAvailable function as in illustrated in the example below.
// Search the PROGRAM MEMORY ID unsigned long iAreaId
// IsBlankCheckAvailable will prevent from executing
// the blank check, when the MCU does not support blank
// check which is the case for the current
// configuration (STM8L15xC6) if ( IsBlankCheckAvailable ("STM8L15xC6","PROGRAM MEMORY")==true)
{
10/30 Doc ID 11472 Rev 6
UM0151 Designing a custom programming application if ( EGetId ("PROGRAM MEMORY", &iAreaId) == 1)
{
// Process all the PROGRAM MEMORY
EBlankAll (iAreaId);
// Blank check between 0x2000 and 0x3000
ECloseComm ( iAreaId, 0x2000L, 0x3000L);
}
}
The programming routine writes the contents of the Memory Image to the specified areas of the device’s memory.
// Search the PROGRAM MEMORY ID unsigned long iAreaId if ( EGetId ("PROGRAM MEMORY", &iAreaId) == 1)
{
// Process all the PROGRAM MEMORY
EProgAll (iAreaId);
// Program only between 0x2000 and 0x3000
EProgArea (iAreaId, 0x2000L, 0x3000L);
}
The verification routine compares the contents of the programmed device memory with the data as you intended to program it. This is the data stored in the Memory Image.
Caution: It is very important not to read the device’s memory prior to verification. When reading the device, the contents of the device’s memory overwrite the contents of the Memory Image, which are used for verification.
// Search the PROGRAM MEMORY ID unsigned long iAreaId if ( EGetId ("PROGRAM MEMORY", &iAreaId) == 1)
{
// Process all the PROGRAM MEMORY
EVerifyAll (iAreaId);
// Read between 0x2000 and 0x3000
EVerifyArea (iAreaId, 0x2000L, 0x3000L);
}
A read routine allows you to read the contents of the target device’s memory.
// Search the PROGRAM MEMORY ID unsigned long iAreaId if ( EGetId ("PROGRAM MEMORY", &iAreaId) == 1)
{
Doc ID 11472 Rev 6 11/30
Designing a custom programming application UM0151
// Process all the PROGRAM MEMORY
EReadAll (iAreaId);
// Read between 0x2000 and 0x3000
EReadArea (iAreaId, 0x2000L, 0x3000L);
}
Caution: Do not to read the device prior to verification. When reading the device, the contents of the device’s memory are stored in the Memory Image, replacing the data that would have been used for verification.
12/30 Doc ID 11472 Rev 6
UM0151
5 DLL supported functions
5.1
DLL supported functions
The following sections provide a detailed description of the programming toolkit’s DLL functions, including those used in the preceding examples. The programming toolkit’s DLL functions are intended to ease access to the STVP programming DLLs.
As a general rule, you can determine which DLL a function calls, by looking at the first letter of the function. For example:
Table 4.
Examples of determining which DLL a function calls
Functions starting with Call For example
C
E
L
DBCA60.DLL
EPRCORE60.DLL
LEF60.DLL
CSetWorkingDir, CGetLastError
ESelectDevice, EProgAll
LOpenLog, LDisplayError
To help you understand their use, we’ve divided the DLL functions into four main categories:
●
●
●
●
Hardware and device configuration functions
DLL environment functions
These functions may be called by your programming application to handle errors, control the process execution, or log the result of basic device actions.
CGetLastError
Returns the last string error occurred after a query to the configuration files
Prototype : char* CGetLastError()
Return : The error string
Clean
Unloads STVP and frees all the resources allocated by the LoadDlls function.
Prototype : void Clean ()
Parameters : None
CSetWorkingDir
Sets the directory where configuration files will be searched for. By default, the configuration files will be searched for in the directory of the calling application.
Prototype : int CSetWorkingDir(const char* szPath)
Parameters : szPath: requested path
Return : 0 if error, 1 if success
Doc ID 11472 Rev 6 13/30
DLL supported functions UM0151
LCloseLog
Closes the currently opened log File
Prototype : int LCloseLog()
Return : 0 if error, 1 if success
LDisplayError
This function is used by the STVP DLLs to display errors. It also logs the error if a log session has been opened. LDisplayError calls the function that has been initialized by
LSetErrorCallBack.
If your application has defined a callback for LDisplayError, this function should be given priority over the internal function, because using it will exercise the logging mechanism.
Prototype : int LDisplayError(const char* szMessage)
Parameters : szMessage: error message text.
Return : 0 if error, 1 if success
LDisplayMessage
This function is used by the STVP DLLs to display messages. It also logs the message if a log session has been opened. In fact LDisplayMessage calls the function that has been initialized by LSetMessageCallBack.
If your application has defined a callback for LDisplayMessage, this function should be given priority over the internal function, because using it will exercise the logging mechanism.
Prototype : int LDisplayMessge(const char* szMessage)
Parameters : szMessage: message text
Return : 0 if error, 1 if success
LDisplayWarning
This function is used by the STVP DLLs to display warnings. It also logs the message if a log session has been opened. LDisplayWarning calls the function that has been initialized by
LSetWarningCallBack.
If your application has defined a callback for LDisplayWarning, this function should be given priority over the internal function, because using it will exercise the logging mechanism.
Prototype : int LDisplayWarning(const char* szMessage)
Parameters : szMessage: warning message text
Return : 0 if error, 1 if success
LoadDlls
Loads the STVP DLLs and retrieves the API addresses. It is not exactly an API function but it should be called prior to any API function otherwise the API function address will not be initialized
Prototype : int BOOL LoadDlls(const char* szDLLPath)
14/30 Doc ID 11472 Rev 6
UM0151 DLL supported functions
Parameters : szDLLPath: The path to access the STVP Programming DLLs
Return :
-1: if error (at least one DLL not loaded or at least one API function not found)
1: if success
LOpenLog
Opens a log file.
If your application has defined callbacks for LDisplayError, LDisplayWarning and
LDisplayMessage, these functions should be given priority over internal functions, because using them will exercise the logging mechanism.
Prototype : int LOpenLog(const char* szFileName)
Parameters : FileName: name of the log file
Return : 0 if error, 1 if success
LSetErrorCallBack
Sets up the error callback function. This function is called by the STVP programming DLLs each time an error occurs during an API function call. The error routine handler should be used to display errors issued by the programming DLLs.
It is not necessary for your application to execute this function, if the error handler has not been set up, nothing is done with the error message and it is lost.
Prototype : int LSetErrorCallBack(long *fonct(const char* szMessage))
Parameters : fonct: Points to the display error handle. The prototype for this function is: long CALLBACK fonct(const char* szMessage)
Return : 0 if error, 1 if success
LSetLogOptions
Configures logging options so only certain kinds of information (Errors, warnings, messages) are stored:
Before using LSetLogOptions, open the logging file name first — LOpenLog .
Prototype : int LSetLogOptions(USHORT Options, OPERATOR ope)
Parameters : Options: One of the following state words defining the messages to log —
LOG_MSG: 1
LOG_WARN: 2
LOG_ERR: 4
LOG_ALL: LOG_MSG | LOG_WARN | LOG_ERR ope: Enum values ‘OR’ or ‘AND’ set and remove an option respectively.
typedef enum {OR, AND} OPERATOR
For example :
.....
LOpenLog( “Activity.log”);
Doc ID 11472 Rev 6 15/30
DLL supported functions UM0151 if (!LSetLogOptions( LOG_ALL, OR)) {
// Log everything
.....
}
.....
// Do not log warnings anymore.
SetLogOption(~LOG_WARN,AND);
.....
Return : 0 if error, 1 if success
LSetMessageCallBack
Sets up the Message callback function. This function is called by the STVP programming
DLLs each time a message occurs during an API function call. Typically the routine handler should be used to display the messages issued by the programming DLLs.
It is not necessary for your application to execute that function, but if the message handler has not been set up the message is lost.
Prototype : int LSetMessage CallBack(long *fonct(const char* szMessage))
Parameters : fonct: Points to the function handler. The prototype for this function is: long CALLBACK fonct(const char* szMessage)
Return : 0 if error, 1 if success
LSetProgressCallBack
This function may used by your application to set up a progress callback function. This function is invoked by the STVP programming DLLs to generate an action progress.
Prototype : int LSetProgress CallBack(long *fonctInt Percentage))
Parameters : fonct: Points to the “in progress” function handler: the prototype for that function must be: long CALLBACK fonct(int iPercent)
Return : 0 if error, 1 if success
LSetWarningCallBack
Sets up the warning callback function. This function is called by the STVP programming
DLLs each time a warning occurs during an API function call. The routine handler should be used to display the warnings issued by the programming DLLs
It is not necessary for your user application to execute that function, if the warning handler has not been set up, nothing is done with the warning and it is lost.
Prototype : int LSetWarningCallBack(long *fonct(const char* szMessage))
Parameters : fonct: Points to the function handler. The prototype for this function is: long CALLBACK fonct(const char* szMessage)
Return : 0 if error, 1 if success
16/30 Doc ID 11472 Rev 6
UM0151
5.2
Note:
DLL supported functions
LTraceLog
Writes a message in the currently opened log file
Prototype : int LTraceLog(const char* Message)
Parameters : Message: The text of the logged message
Return : 0 if error, 1 if success
Hardware and device configuration functions
These functions allow you to select and configure both the programming hardware (EPB,
ST7-STICK, DVP3, EMU3, STice, ST-LINK, ST-TSLINK and Raisonance STX-RLINK), device, protocol and communication port that will be used during the programming session.
The list of supported hardware, ports, protocols and devices are the same as those supported by STVP. These are displayed in the Configure ST Visual Programmer dialog
ESelectDevice
Selects the device to be programmed.
Prototype : int ESelectDevice(const char* szDevice)
Parameters : szDevice: device name
Return : 0 if error, 1 if success
ESelectHard
Select the programming hardware (EPB, DVP3, EMU3, ST7-STICK, STice, ST-LINK, ST-
TSLINK or Raisonance STX-RLINK) and the protocol to be used.
The list of available protocols on the target hardware and device. You will find this information in STVP’s Configure ST Visual Programmer dialog box, or you can use the function GetProtocolList provided by the programming toolkit.
Prototype : int ESelectHard(const char* szCard, const char* szProtocol,BOOL bDemo)
Parameters : szCard: hardware programming board szProtocol: protocol name bDemo: TRUE for device simulation, meaning that the programming software does not connect to the programming hardware.
Return : 0 if error, 1 if success
ESelectPort
Selects the communication port.
Prototype : int ESelectPort(const char* szPort)
Parameters : szPort: The port name (LPT1, USB, etc.)
Return : 0 if error, 1 if success
Doc ID 11472 Rev 6 17/30
DLL supported functions
Note:
Note:
UM0151
ESetPreferences
Enables or disables the preferences. Only "Protection Warnings" can be disabled/enabled for the moment. Disabling prevents a dialog box from being opened when the protection bit in the Option byte is to be programmed.
This function must be called after the ESelectHard function call and before each
ESelectDevice function call.
Prototype : int ESetPreferences(int iPreference, BOOL bState)
Parameters :
Preference: Preference for example: PROTECTION_WARNING=0x01) bState: TRUE or FALSE
Return : 0 if error, 1 if success
ESetProtection
On some MCU, it enables or disables protection on specific addresses for instance the RC
Calibration on ST7FLITE09. When a protection is set, the relevant addresses are not programmed
Protection mode is expressed as a string. The list of protection modes can be found either in
STVP’s Configuration dialog box, or at run time by using the GetProtectionList function from the Programming Toolkit .
Prototype : int ESetProtection(const char* szProtectMode, BOOL bState)
Parameters : szProtectMode: The literal string for the protection mode. Example "Protect RC
Calibration values on Program Memory".
bState: TRUE to enable or FALSE to disabled the protection.
Return : 0 if error, 1 if success
5.3 Image area access functions
The following functions allow you to retrieve and store information in the buffer called the
Memory Image that the programming software creates on your PC.
ECheckSum
Returns the checksum from the last file loaded and the current memory checksum
Prototype : int ECheckSum(DWORD dwAreaId, long *FileCheckSum, long
*MemoryCheckSum)
Parameters : dwAreaId: Area identifier
FileCheckSum: Last file checksum
MemoryCheckSum: Current memory checksum
Return : 0 if error, 1 if success
18/30 Doc ID 11472 Rev 6
UM0151
Note:
DLL supported functions
EGetId
Returns the unique identifier for the specified area.
Prototype : int EGetId(const char* szName, DWORD* pdwId)
Parameters : szName: Literal name for the programming area (For example, PROGRAM MEMORY, or OPTION BYTE).
pdwId: Pointer with the area identifier
Return : 0 if error, 1 if success
EGetImagePtr
Returns the pointer the size of the specified area in the Memory Image.
Prototype : char far *EGetImagePtr(DWORD dwAreaId, long *MemSize
)
Parameters : dwAreaId: Area identifier
MemSize: Memory size
Be careful when using a pointer to the memory image buffer, you should use the physical address for the area that you want to access as indexed in the buffer. The programming toolkit’s GetByteInImageMemory or SetByteInImageMemory helper functions should be used instead of read or write in the memory image functions.
Return : The memory image pointer is NULL if non existent memory
For example :
// Write 0x5A in PROGRAM MEMORY memory image at adress 0x8000 char* pImgMemory; unsigned long dwAreaId long lMemSize; if (EGetId("PROGRAM MEMORY",&dwAreaID)==1)
{ pImgMemory = EGetImagePtr(dwAreaID,&lMemSize) if (pImgMemory)
{ pImgMemory[0x8000] = 0x5A;
}
}
ELoadFile
Loads a binary file in the memory image. Supported binary formats are Motorola .S19 and
Intel .HEX
Prototype : int ELoadFile(const char* FileName, DWORD dwAreaId)
Parameters :
FileName: The name of the binary file dwAreaId: Area identifier, see EGetId .
Doc ID 11472 Rev 6 19/30
DLL supported functions
Note:
UM0151
Return : 0 if error, 1 if success
ESaveFile
Saves the memory image in a binary file
The binary format used to save the file depends on the extension of the FileName parameter. The .S19 extension will generate a Motorola S19 file, .HEX extension generates an Intel HEX binary file
Prototype : int ESaveFile(const char* FileName, DWORD dwAreaId)
Parameters :
FileName: The binary file name dwAreaId: Area identifier
Return : 0 if error, 1 if success
5.4 Device connection functions
This section describes all the functions that physically interact with the device that is to be programmed: blank check, program, verify and read.
● Blank check ensures that the device memory area is programmed with the default value.
●
●
Programming the device programs the device’s memory with the values currently stored in the Memory Image.
Verify compares the value for each address of a specified area in the Memory Image, with that stored in the device’s memory.
● Reading the device fills the Memory Image for the specified area with values read from the device’s memory.
EBlankAll
Blank checks the entire target memory area. Works only on FLASH and EPROM memory.
Prototype : int EBlankAll(DWORD dwAreaId)
Parameters : wAreaId: Area identifier
Return : 0 if error, 1 if success
EBlankArea
Blank checks a part of the device’s memory.
Prototype : int EBlankArea(DWORD dwAreaId,long FirstAddr,long LastAddr)
Parameters : dwAreaId: Area identifier
FirstAddr: 1st device memory address
LastAddr: Last device memory address
Return : 0 if error, 1 if success
20/30 Doc ID 11472 Rev 6
UM0151 DLL supported functions
ECloseComm
Close communication with the board.
For some tools, it is mandatory to close communication before leaving the application.
Prototype : int ECloseComm()
Parameter s: None
Return : 0 if error, 1 if success
EEraseAll
Erases all the sectors of FLASH memory.
Prototype : int EEraseAll(DWORD dwAreaId)
Parameters : dwAreaId: Area identifier.
Return : 0 if error, 1 if success
EEraseArea
Erases a target FLASH memory sector. FirstAddr and LastAddr must map the sector to be erased exactly.
Prototype : int EEraseArea(DWORD dwAreaId,long FirstAddr,long LastAddr)
Parameters : dwAreaId: Area identifier
FirstAddr: 1st device memory address
LastAddr: Last device memory address
Return : 0 if error, 1 if success
EProgAll
Programs the entire device memory.
Prototype : int EProgAll(DWORD dwAreaId)
Parameters : dwAreaId: Area identifier
Return : 0 if error, 1 if success
EProgArea
Programs part of the device’s memory. Do not use this function to program OPTION BYTE.
OPTION BYTE must be programmed all at once using EProgAll function and not bit-by-bit.
Prototype : int EProgArea(DWORD dwAreaId, long FirstAddr,long LastAddr)
Parameters : dwAreaId: Area identifier
FirstAddr: 1st device memory address
LastAddr: Last device memory address
Return : 0 if error, 1 if success
Doc ID 11472 Rev 6 21/30
DLL supported functions UM0151
EReadAll
Reads the entire device memory area.
Prototype : int EReadAll(DWORD dwAreaId)
Parameters : dwAreaId: Area identifier
Return : 0 if error, 1 if success
EReadArea
Reads a part of the device’s memory area. Do not use this function to read the OPTION
BYTE. The full OPTION BYTE must be read at once using the EAllRead function and not bit-by-bit.
Prototype : int EReadArea(DWORD dwAreaId, long FirstAddr, long LastAddr)
Parameters : dwAreaId: Area identifier
FirstAddr: 1st device memory address
LastAddr: Last device memory address
Return : 0 if error, 1 if success
EVerifyAll
Verifies the entire memory area of the programmed device.
Prototype : int EVerifyAll(DWORD dwAreaId)
Parameters : dwAreaId: area identifier
Return : 0 if error, 1 if success
EVerifyArea
Verifies a part of the target memory area. Do not use this function to verify the OPTION
BYTE. The full OPTION BYTE must be verified at once using the EVerifyAll function and not bit-by-bit.
Prototype : int EVerifyArea(DWORD dwAreaId, long FirstAddr,long LastAddr)
Parameters : dwAreaId: area identifier
FirstAddr: 1st device memory address
LastAddr: Last device memory address
Return : 0 if error, 1 if success
22/30 Doc ID 11472 Rev 6
UM0151
6
Programming toolkit helper functions
Programming toolkit helper functions
Note:
This section describes the functions that extract the most useful requests to the configuration file databases and a few functions that allow the application to write to and read the Memory Image. These functions are located in the PtkToolBox.cpp C source file.
The functions below should be used to access to the configuration information as the database file format may change without notification. Even if the format of the database changes, the prototype for the Helper Functions will remain the same.
FillImageMemory
Fills the memory image with the blank value.
Prototype : int FillImageMemory(const char* szDeviceName, const char* szAreaName)
Parameters : szDeviceName: device name szAreaName: name of the area
Return : 0 if error, 1 if success
GetAreaList
Fills the output buffer with the list of memory areas (PROGRAM, DATA, OPTION...) that are supported by a particular device. In the output buffer, the items in the list are separated by
’\n’. When the function returns an error, the error is due to a database access problem. Use the CGetLastError function to retrieve the error message.
Prototype : int GetAreaList(const char*szDeviceName, char* szListBuffer, int iBufferSize)
Parameters : szDeviceName: device name szListBuffer: output buffer that contains the list of memory areas iBufferSize: size of the output buffer
Return : 0 if error, 1 if success
GetAreaMapping
Returns the address range (first and last addresses) of a given memory area. If the area mapping is split in several sectors, FirstAddr contains the lower address of the first section and LastAddr contains the higher address of the last section.
Prototype : int GetAreaMapping(const char* szDevice,const char* szAreaName, unsigned long *FirstAddr, unsigned long LastAddress)
Parameters : szDeviceName: device name szAreaName: name of the area
FirstAddr: output parameter that contains the first area address
LastAddr: output parameter that contains the last area address
Return : 0 if error, 1 if success
Doc ID 11472 Rev 6 23/30
Programming toolkit helper functions
Note:
UM0151
GetByteFromImageMemory
Reads a byte at a given address in the memory image.
Prototype : int GetByteFromImageMemory(const char* szDeviceName, const char* szAreaName, unsigned long dwAddr, unsigned char* uValue )
Parameters : szDeviceName: device name szAreaName: name of the area dwAddr: memory image address to be written uValue: byte value to write
Return : 0 if error, 1 if success
GetDeviceList
Fills the output buffer with the list of devices supported by a particular protocol for a particular programming hardware.
In the Output buffer, the items in the list are separated with ’\n’
When the function returns an error, the error is due to a database access problem. Use the
CGetLastError function to retrieve the error message.
Prototype : int GetDeviceList(const char* szHardName, const char* szProtocolName, char* szListBuffer, int iBufferSize)
Parameters : szHardName: board name szProtocolName: name of the protocol to be used szListBuffer: output buffer that contains the list of devices matching with the board and the protocol iBufferSize: size of the output buffer
Return : 0 if error, 1 if success
GetHardwareList
Fills a buffer with the list of programming hardware currently supported by the configuration database. In the Output buffer, the items in the list are separated with ’\n’ .
When the function returns an error, the error is due to a Data base access problem, use the
CGetLastError function to get the error message
Prototype : int GetHardwareList(char* szListBuffer, int iBufferSize)
Parameters : szListBuffer: output buffer that contains the list of programming hardware iBufferSize: size of the output buffer
Return : 0 if error, 1 if success
GetNextMapSector
Iterates on all sectors from the area mapping. When initiating the iteration, the
GetNextMapSector function should be called with szDevice and szAreaName initialized.
24/30 Doc ID 11472 Rev 6
UM0151 Programming toolkit helper functions
During the iteration, GetNextMapSector should be called with a NULL value for szDevice and szAreaName.
Prototype : int GetNextMapSector((const char* szDevice,const char* szAreaName, unsigned long *FirstAddr, unsigned long LastAddress)
Parameters : szDeviceName: device name szAreaName: name of the area
FirstAddr: output parameter that contains the first sector address
LastAddr: output parameter that contains the last sector address
Return :
0 if error
1 if there is at least one more sector
-1 if the end of the mapping has been reached
For example unsigned long FirstAreaAddr,lLastAreaAddr; any = GetNextMapSector("ST7FLCD1","PROGRAM MEMORY",
&FirstAddr,LastAreaAddr); while (any == 1)
{ any = GetNextMapSector(NULL,NULL,&FirstAreaAddr,
&lLastAreaAddr);
}
// Reach end of map
GetPortList
Fills the output buffer with the list of communication ports that may be used to connect with a particular board. In the Output buffer, the items in the list are separated by ‘\n’.
When the function returns an error, the error is due to a database access problem. Use the
CGetLastError function to retrieve the error message.
Prototype : int GetPortList(const char* szHardName, char* szListBuffer, int BufferSize)
Parameters : szHardName: name of the programming hardware szListBuffer: output buffer that contains the list of ports supported by the programming hardware iBufferSize: size of the output buffer
Return : 0 if error, 1 if success
GetProtectionList
Fills the output buffer with the list of protections supported by a given device.
Doc ID 11472 Rev 6 25/30
Programming toolkit helper functions
Note:
UM0151
Protection is an optional state that allows user to protect some reserved addresses, for instance the RC Calibration bytes for some ST7LITE microcontrollers. When protection is set, the relevant addresses are not programmed (see ESetProtection ).
In the Output buffer, the items in the list are separated by ’\n’.
When the function returns an error, the error is due to a database access problem. Use the
CGetLastError function to retrieve the error message.
Prototype : int GetProtectionList(const char*szDeviceName, char* szListBuffer, int iBufferSize)
Parameters : szDeviceName: device name szListBuffer: output buffer that contains the list of protection options supported by the device iBufferSize: size of the output buffer
Return : 0 if error, 1 if success
GetProtocolList
Fills the output buffer with the list of protocols supported by a particular board. In the output buffer, the items in the list are separated by ’\n’. When the function returns an error, the error is due to a database access problem. Use the CGetLastError function to retrieve the error message.
Prototype : int GetProtocolList(const char* szHardName,char* szListBuffer, int iBufferSize)
Parameters : szHardName: board name szListBuffer: output buffer that contains the list of protocols supported by the programming board
BufferSize: size of the output buffer
Return : 0 if error, 1 if success
IsBlankCheckAvailable
Indicates whether a given area may be blank checked. Blank check can be done only on
Flash and EPROM areas
Prototype : int IsBlankCheckAvailable(const char* szDeviceName, const char* szAreaName)
Parameters : szDeviceName: device name szAreaName: name of the area
Return :
0: blank check is not allowed on the area
1: if the area may be blank checked
26/30 Doc ID 11472 Rev 6
UM0151 Programming toolkit helper functions
IsErasableArea
Indicates whether a given area may be erased. Only Flash areas are erasable.
Prototype : int IsErasableArea(const char* szDeviceName, const char* szAreaName)
Parameters : szDeviceName: device name szAreaName: name of the area
Return :
0: area is not erasable
1: area may be erased
SetByteInImageMemory
Writes a byte in the memory image at a given address.
Prototype : int SetByteInImageMemory(const char* szDeviceName, const char* szAreaName, unsigned long dwAddr, unsigned char uValue)
Parameters : szDeviceName: device name szAreaName: name of the area dwAddr: memory image address to be written uValue: byte value to write
Return : 0 if error, 1 if success
Doc ID 11472 Rev 6 27/30
Product support
Appendix A Product support
UM0151
If you experience any problems with this product, or if you need spare parts or repairs, contact the distributor or the STMicroelectronics sales office where you purchased the product. Phone numbers for major sales regions are provided on the www.st.com
web site.
From the www.st.com
site, select Products > Microcontrollers to obtain a complete online selection guide, as well as documentation, software downloads and user discussion groups to help you answer questions and stay up to date with our latest product developments.
Software updates
All our latest software and related documentation are available for download from the
STMicroelectronics internet site, www.st.com
.
If you are using software from a third-party tool provider, please refer to the third-party for software product support and downloads.
28/30 Doc ID 11472 Rev 6
UM0151 Revision history
Table 5.
Date
01-Apr-2004
15-Jul-2005
06-Apr-2009
21-Jan-2010
10-Jun-2011
19-Mar-2012
Document revision history
Revision
1
2
3
4
5
6
Changes
Initial release.
– Added ST7SB Socket Board to supported hardware in Introduction
– Updated Figure 1 – showing supported programming hardware
– Updated About the user manuals – list of supporting documentation
– Updated internet address in Getting assistance
– Updated Table 1 – installed components
Revalidation
– Corrected revision numbers
– Updated to new template
– Updated to new template
– Updated to support STM8, STice, ST-LINK, ST-TSLINK and
Raisonance STX-RLINK
– Updated to support STM32
– Corrected some code examples on area name "PROGRAM
MEMORY" (use a space character instead of '_').
– Updated examples to use an ST-LINK and STM8 device.
– Updated
Table 2: Source files and executables for two sample applications: on page 5
– Replaced APISample.exe with STVP_CmdLine.exe
– Changed “Example” format (codes)
Doc ID 11472 Rev 6 29/30
UM0151
Please Read Carefully:
Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any time, without notice.
All ST products are sold pursuant to ST’s terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein.
UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS EXPRESSLY APPROVED IN WRITING BY TWO AUTHORIZED ST REPRESENTATIVES, ST PRODUCTS ARE NOT
RECOMMENDED, AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING
APPLICATIONS, NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY,
DEATH, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE. ST PRODUCTS WHICH ARE NOT SPECIFIED AS "AUTOMOTIVE
GRADE" MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER’S OWN RISK.
Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any liability of ST.
ST and the ST logo are trademarks or registered trademarks of ST in various countries.
Information in this document supersedes and replaces all information previously supplied.
The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.
© 2012 STMicroelectronics - All rights reserved
STMicroelectronics group of companies
Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan -
Malaysia - Malta - Morocco - Philippines - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America www.st.com
30/30 Doc ID 11472 Rev 6
Stáhnout
Veřejný odkaz aktualizován
Veřejný odkaz na váš chat byl aktualizován. You may view and manage your chat links after registration here.
Veřejný odkaz na dokument
Reklama
