Softlog Programmers DLL Description

Softlog Systems (2006) Ltd.
ICP Family Programmers: DLL Description
1
Installation ................................................................................................................................................... 2
1.1
Install "ICP for Windows" .................................................................................................................... 2
1.2
Install "ICP DLL" ................................................................................................................................. 2
2 ICP Firmware Options ................................................................................................................................. 2
3 General Sequence of Operations ................................................................................................................ 2
4 Configuration File (*.cfg) ............................................................................................................................. 3
5 Quick Start ................................................................................................................................................... 3
6 Base Functions ............................................................................................................................................ 3
6.1
IcpStartApplication .............................................................................................................................. 3
6.2
IcpInitCom........................................................................................................................................... 4
6.3
IcpLoadHexAndSerFile ....................................................................................................................... 4
6.4
IcpTestConnection .............................................................................................................................. 4
6.5
IcpDoAction ........................................................................................................................................ 4
6.6
IcpReleaseCom .................................................................................................................................. 5
6.7
IcpEndApplication ............................................................................................................................... 6
6.8
IcpReadDllVersion .............................................................................................................................. 6
6.9
IcpEnableProgressWindow ................................................................................................................ 6
6.10 IcpDllSelectProg ................................................................................................................................. 6
7 Standalone Operation: General Functions .................................................................................................. 6
7.1
IcpDoAction – see ‎6.5 ........................................................................................................................ 6
7.2
IcpDllGetInfoSingle ............................................................................................................................. 6
7.3
IcpReadStaResOneCh ....................................................................................................................... 7
8 Standalone Operation: Create/Transfer Environment ................................................................................. 8
8.1
IcpSaveEnvironment .......................................................................................................................... 8
8.2
IcpTransferEnvironmentToIcp ............................................................................................................ 8
9 Standalone Operation: RAM Buffer............................................................................................................. 9
9.1
IcpRamUsage ..................................................................................................................................... 9
9.2
IcpRamBufWrite ................................................................................................................................. 9
9.3
IcpRamBufRead ................................................................................................................................. 9
10
Standalone Operation: Multiple Environments .....................................................................................10
10.1 IcpSwitchEnv ....................................................................................................................................10
11
PC-Driven Operation: Access to PC Memory Buffers ..........................................................................10
11.1 IcpGetBuffers ....................................................................................................................................10
12
Direct Hardware Control .......................................................................................................................11
13
More DLL Functions .............................................................................................................................11
14
Appendix A: Return Values and Definitions .........................................................................................11
14.1 Return Values ...................................................................................................................................11
14.2 Definitions .........................................................................................................................................12
14.2.1
Action List .................................................................................................................................12
14.2.2
Memory Spaces (PC-driven Operation) ...................................................................................12
14.2.3
Programmer Type and Mode ....................................................................................................13
14.2.4
Usage of RAM Buffer ................................................................................................................13
14.2.5
Environment Status ..................................................................................................................13
14.2.6
Additional Definitions ................................................................................................................13
15
Appendix B: Software Examples ..........................................................................................................13
15.1 Software Example: PC-Driven Mode, Single Channel .....................................................................13
15.2 Software Example: Standalone Mode, Gang Programming ............................................................14
15.3 More Software Examples .................................................................................................................16
16
Technical Assistance ............................................................................................................................17
17
Warranty ...............................................................................................................................................17
18
Contact .................................................................................................................................................17
19
Copyright Notice ...................................................................................................................................17
Web: www.softlog.com, E-mail: [email protected], [email protected]
ICP Family DLL Description
1 Installation
1.1
Install "ICP for Windows"
Run "ICP for Windows" setup file "IcpWin_setup_xxx.exe". It can be obtained from supplied CD or
downloaded from:
http://softlog.com/index.asp?page=Downloads&parentid=5#ICP_Family_GUI_Software
This manual presumes that your are familiar with "ICP for Windows" software
1.2
Install "ICP DLL"
Run DLL setup file "IcpDll_setup_dll_xxx.exe". It can be obtained from supplied CD or downloaded from:
http://www.softlog.com/index.asp?page=Downloads&parentid=5#ICP_Family_DLL_Software_
The following files will be installed to the default directory "C:\Program Files\Soft-Log\IcpDll":
### File Name
Description
1.
IcpDll.dll
ICP DLL
2.
IcpWinComLine.exe
ICP Command line utility. See document
"ICP Command Line.pdf" for details
3.
c_icpexp.h
Header file with ICP DLL functions
4.
fr_exp.h
Header file with ICP DLL definitions
5.
fr_icp2.h
Header file with ICP2 hardware definitions
6.
DLL Description.pdf
This document
7.
ICP Command Line.pdf
ICP Command line utility description
8.
ICP2 - FTM Functions.pdf
Description of ICP FTM (final test machine) functions
9.
\Lib_Borland\IcpDll.lib
LIB file for Borland C Builder
10. \Lib_Microsoft\IcpDll.lib
LIB file for Microsoft C++
11. \VB_Microsoft\c_icpexp.bas
Header file with ICP DLL functions for Microsoft Visual Basic
2 ICP Firmware Options
DLL/Command Line Support (D) should present in order to use DLL functions. Order Softlog programmers
with "D" suffix, for example ICP2-D or ICP2GANG-D or activate "D" support remotely. For more details see
page 2 of http://softlog.com/userfiles/file/Downloads/Comparison.pdf or contact Softlog Systems
Use the following sequence to validate your ICP firmware options:
- connect the programmer unit to the PC
- run "ICP for Windows"
- if programmer is connected and communication is OK then press "Details" button on "About" screen
- if incorrect COM is selected then open "Communication→RS-232/USB/Bluetooth COM", select the
detected COM and press OK, then press "Details" as specified above
3 General Sequence of Operations
Step
1.
Function
IcpStartApplication()
Description
Starts ICP application
2.
IcpInitCom()
Initializes COM port
3.
IcpLoadHexAndSerFile()
4.
IcpDoAction()
5.
6.
IcpReleaseCom()
IcpEndApplication()
Loads hex and/or
serialization files
Executes action according
to ACTION_LIST
Releases COM port
Closes the application
Rev: 4.7.3 Jan-2011
Usage
Should be called once before other ICP
DLL functions can be called, mandatory.
Next call can be only done after application
is closed by IcpEndApplication()
Once, mandatory if communication is
required. Next call can be done after COM
is released by IcpReleaseCom()
Once or repeated,
mandatory in PC-driven mode
Once or repeated, not mandatory
Once or repeated, not mandatory
Once, mandatory
Page 2 of 17
ICP Family DLL Description
4 Configuration File (*.cfg)
Function IcpStartApplication() uses ICP configuration file ("icp01.cfg") as a parameter. The following
procedure is recommended for preparing "icp01.cfg: file:
 Run "ICP for Windows" software
 Select programmer: "Programmer → Select Programmer"
 Select COM: "Communication → RS-232/USB/Bluetooth COM"
 Select device to be programmed: "Device → Select by Name"
 Set desired voltages, etc.: "Options → Voltages"
 Save configuration file: "File → Save Configuration"
 Validate that interactive programming works correctly
 Exit the software
 Copy "icp01.cfg" to your project directory and rename. NOTE: "icp01.cfg" is usually located in directory
"C:\Program Files\Soft-Log\IcpWin"
5 Quick Start










Install ICP DLL as described in chapter ‎1 to directory "C:\Program Files\Soft-Log\IcpDll"
Prepare "icp01.cfg" file as described in chapter ‎4
Create project directory, for example "C:\MyProject"
Run Visual C++ and create a new project, for example Project1
Copy ICP DLL files from "C:\Program Files\Soft-Log\IcpDll" as follows:
- to "C:\MyProject":
- "c_icpexp.h"
- "fr_exp.h"
- "IcpDll.lib" (from "C:\Program Files\Soft-Log\IcpDll\Lib_Microsoft")
- to "C:\MyProject\Debug":
- Icp01.cfg
- IcpDll.dll
Define "IcpDll.lib" as a part of the project:
- Visual Studio C++ 6.0:
- select menu item “Project->Settings”
- select tab Link
- select mode “All Configurations” in combo box “Settings For”
- fill field “Object/library modules” with string “IcpDll.lib”
- press OK
- Visual Studio C++ 2008:
- select menu item “Project->Properties”
- select tree items “Linker->Input”
- select mode “All Configurations” in combo box “Configuration”
- fill field “Additional Dependencies” with string “IcpDll.lib”
- press OK
Write a simple PC-driven application – see example in chapter ‎15.1
Select Debug mode, compile and run the application
After debugging is done copy files "Icp01.cfg" and "IcpDll.dll" from directory "C:\MyProject\Debug" to
"C:\MyProject\Release"
Select Release mode, compile and run the application
6 Base Functions
6.1
IcpStartApplication
Description:
Prototype:
Parameters:
Example:
Starts application and loads configuration file
int DLL_FUNC IcpStartApplication (char *aFileCfg)
aFileCfg - ICP configuration file to be loaded, usually "icp01.cfg"
int Stat = IcpStartApplication ("c:\MyProject\Icp01.cfg");
Rev: 4.7.3 Jan-2011
Page 3 of 17
ICP Family DLL Description
6.2
IcpInitCom
Description:
Prototype:
Parameters:
Example:
6.3
Initializes RS-232/USB/Bluetooth COM port
int DLL_FUNC IcpInitCom (int aOverCfg, int aComPort, int aBaudRate)
aOverCfg:
0-gets communication parameters from *.cfg file
1-overrides *.cfg file with aPort and aBaudRate
aPort:
0-COM1, 1-COM2,...
aBaudRate:
see enum BAUD_RATES (file fr_exp.h)
Stat = IcpInitCom( 0, 0, 0 ); //use settings from *.cfg file
IcpLoadHexAndSerFile
Description:
Prototype:
Parameters:
Loads HEX and serialization files
int DLL_FUNC IcpLoadHexAndSerFile (char *aFileHex, char *aFileSer)
aFileHex - pointer to char string that contains HEX file name
aFileSer - pointer to char string that contains serialization file name
Example 1:
Stat = IcpLoadHexAndSerFile ("c:\MyProject\1.hex", "c:\MyProject\1.ser");
Example 2:
Stat = IcpLoadHexAndSerFile ("c:\MyProject\1.hex", ""); //hex file only
Example 3:
Stat = IcpLoadHexAndSerFile ("", "c:\MyProject\1.ser"); //serialization file
//only (standalone operation)
6.4
IcpTestConnection
Description:
Prototype:
Parameters:
Example:
6.5
Description: communicates with the programmer as follows:
- if ICP2 then with ICP2
- if GANG then with channel 2
- if GANG(single channel) then with the selected channel
No LEDs are activated on the programmer (blind connection)
int DLL_FUNC IcpTestConnection(void)
None
int err= IcpTestConnection();
if (err != AUTO_OK) //(see errorcodes in chapter ‎14)
<means communication error>
IcpDoAction
Description:
Executes programming, verification and other actions specified in
enum ACTION_LIST – see ‎14.2.1
Prototype:
int DLL_FUNC IcpDoAction(
Parameters:
aAction: one of values of ACTION_LIST. Note: ICP software automatically removes memory
spaces which do not exist in the selected device
int aAction,
unsigned int aMemorySpace,
unsigned int aPmUserRange,
unsigned int aPmAddrBeg,
unsigned int aPmAddrEnd,
unsigned int aSaveResult,
char* aReadFile );
aMemorySpace: sum of memory spaces - see MEMORY_SPACES in ‎14.2.2
Rev: 4.7.3 Jan-2011
Page 4 of 17
ICP Family DLL Description
aPmUserRange:
0-use full PM range,
1-override with aPmAddrBeg and aPmAddrEnd
aPmAddrBeg:
aPmAddrEnd:
aSaveResult:
aReadFile:
start address of PM (if aPmUserRange=1)
end address of PM (if aPmUserRange=1)
1-operation result will be written to file "auto01.res"
hex file to be saved after read (if aAction=ACT_READ)
Example 1 (PC-driven mode): Program (and verify) entire chip
int Stat = IcpDoAction( ACT_PROG,
ALL_SPACE,
0,
0,
0,
0,
“”);
//aAction
//aMemorySpace
//aPmUserRange
//aPmAddrBeg
//aPmAddrEnd
//aSaveResult
//aReadFile
Example 2 (PC-driven mode): Verify locations 0x0020-0x003F of PM
Stat = IcpDoAction(
ACT_VER,
PM_SPACE,
1,
0x0020,
0x003F,
0,
“”);
//aAction
//aMemorySpace
//aPmUserRange
//aPmAddrBeg
//aPmAddrEnd
//aSaveResult
//aReadFile
Example 3 (PC-driven mode): Read entire chip to file "c:\prj\hex1.hex"
Stat = IcpDoAction(
ACT_READ,
//aAction
ALL_SPACE,
//aMemorySpace
0,
//aPmUserRange
0,
//aPmAddrBeg
0,
//aPmAddrEnd
0,
//aSaveResult
"c:\prj\hex1.hex");
//aReadFile
Example 4 (Standalone mode): Program (and verify) all chip(s)
int Stat = IcpDoAction( ACT_STA_PROG,
ALL_SPACE,
0,
0,
0,
0,
“”);
//aAction
//aMemorySpace (Note 1)
//aPmUserRange
//aPmAddrBeg
//aPmAddrEnd
//aSaveResult
//aReadFile
Note 1: aMemorySpace parameter does not affect standalone operation since memory space is selected
according to environment settings saved in ICP2 internal flash memory
6.6
IcpReleaseCom
Description:
Prototype:
Parameters:
Releases serial communication port
int DLL_FUNC IcpReleaseCom (void)
None
Example:
Stat = IcpReleaseCom();
Rev: 4.7.3 Jan-2011
Page 5 of 17
ICP Family DLL Description
6.7
IcpEndApplication
Description:
Prototype:
Parameters:
Terminates ICP DLL application
int DLL_FUNC IcpEndApplication (void)
None
Example:
Stat = IcpEndApplication();
6.8
IcpReadDllVersion
Description:
Prototype:
Parameters:
Gets DLL version string
int DLL_FUNC IcpReadDllVersion (char *dllSoftwareVer)
dllSoftwareVer – pointer to DLL version string
Example:
char DllVersion[80];
Stat = IcpReadDllVersion (DllVersion);
6.9
IcpEnableProgressWindow
Description:
Prototype:
Parameters:
Enables/disables progress window (progress bar)
int DLL_FUNC IcpEnableProgressWindow(int aEnable);
aEnable: 0-disable, 1-enable
6.10 IcpDllSelectProg
Description:
Selects programmer type and mode by overwriting value from *.cfg file,
useful to switch between ICP2-GANG channels and standalone/PC-driven modes
Prototype:
Parameters:
int DLL_FUNC IcpDllSelectProg(int aProg, int aMode, int aCh)
aProg - programmer according to enum PROG_TYPE – see ‎14.2.3
aMode - mode of operation according to enum PROG_MODE – see ‎14.2.3
aCh - current channel for "GANG-single channel" programmer, 0 for channel 1
Return Value: A) AUTO_OK if parameters are correct
B) -1: parameter 1 is not correct
-2: parameter 2 is not correct
-3: parameter 3 is not correct
Example:
Select channel 2 of ICP2-GANG programmer for PC-driven operation, then restore to GANG
IcpDllSelectProg(PROG_GANG4_SINGLECHAN, SPM_PCDRIVEN,1);
... - execute desired PC-driven operations with channel 2
IcpDllSelectProg(PROG_GANG4, SPM_STANDALONE, 0); //restore GANG standalone
7 Standalone Operation: General Functions
7.1
IcpDoAction – see ‎6.5
See IcpDoAction() with parameters ACT_STA_PROG, ACT_STA_GET_RES and
ACT_STA_START_PROG
7.2
IcpDllGetInfoSingle
enum INFO_ICP_OPTIONS {
INFO_OPT_DLL
= 0x0001, //1-DLL support enabled
INFO_OPT_DSPIC
= 0x0002, //1-dsPIC support enabled
INFO_OPT_KEE
= 0x0004, //1-Keeloq support enabled
INFO_OPT_SEC
= 0x0008, //1-security feature support enabled
Rev: 4.7.3 Jan-2011
Page 6 of 17
ICP Family DLL Description
INFO_OPT_PIC32
};
= 0x0010 //1-PIC32 support enabled
#define INFO_ID_SIZE
#define INFO_GANG_QUAN
3 //firmware ID length
64 //maximum number of GANG channels
typedef struct //info from one channel of ICP2/ICP2-GANG
{
int iValid;
//1-information in this structure is valid
unsigned short iProgType;
//programmer type according to PROG_TYPE
unsigned short iFirmVer;
//firmware version (H.L)
unsigned char iIcpId[INFO_ID_SIZE]; //firmware ID (ICP serial number)
unsigned short iBootVer;
//bootloader version (H.L)
unsigned short iIcpOpt;
//ICP enabled options according to INFO_ICP_OPTIONS above
unsigned short iFirmDevDb;
//firmware device database version (H.L.)
unsigned short iFirmPrjDb;
//firmware project database version (H.L.)
unsigned short iDllDevDb;
//DLL device database version (H.L.)
unsigned short iDllPrjDb;
//DLL project database version (H.L.)
int iSecMode;
//security mode (1-secure environment now)
int iEnvStat;
//environment status according to enum PRJ_VAL – see ‎14.2.5
char iEnvHexFileName[SEC_ID_SIZE];//HEX file name inside the environment
unsigned short iEnvHexFileCs;
//HEX file checksum
char iSecIdName[SEC_ID_SIZE];
//Security ID name
int iSecCntValue;
//value of non-volatile security counter
int iSecCntInteg;
//security counter integrity (0-OK)
} ICP_INFO;
Description:
Prototype:
Parameters:
Get environment and ICP general info from a single channel
int DLL_FUNC IcpDllGetInfoSingle(ICP_INFO *aInfo)
aInfo - pointer to ICP_INFO structure
Example:
Validate that environment is OK and HEX file checksum is 0x1234
ICP_INFO MyInfo;
IcpDllGetInfoSingle(&MyInfo);
if (! MyInfo.iValid) //invalid environment
return 1;
if (MyInfo.iEnvHexFileCs != 0x1234)
return 2;
return 0; //OK
7.3
IcpReadStaResOneCh
Description:
Reads result of standalone operation for one channel. Should be called in
loop for all channels after previous programming is done
Prototype:
int DLL_FUNC IcpReadStaResOneCh(unsigned int aCh);
Parameters: aCh: channel number, range 0...63. NOTE: aCh is 0 for ICP2 (not GANG)
Return Value: A) -1 if channel is not enabled
B) -2 if channel number is out of range (>63)
C) according to AUTO_ERROR_LEVEL
Example:
Program 8 channels of ICP2-GANG and get results
Rev: 4.7.3 Jan-2011
Page 7 of 17
ICP Family DLL Description
Step 1: Execute standalone programming for 8 channels
#define CH_NUM 8 //8 channels
int Res[CH_NUM];
int Stat = IcpDoAction( ACT_STA_PROG,
0,
0,
0,
0,
0,
“”);
//aAction
//aMemorySpace
//aPmUserRange
//aPmAddrBeg
//aPmAddrEnd
//aSaveResult
//aReadFile
Step 2: Analyze result
if (Stat==AUTO_OK) {
; //do nothing, all channels OK
}
else {
for (int i=0; i<CH_NUM; i++)
Res[i]= IcpReadStaResOneCh[i]; //save all results
{
8 Standalone Operation: Create/Transfer Environment
Simultaneous GANG programming can be done in standalone mode only. An environment should be created
and transferred to the programmer unit before programming takes place
An environment can be created and transferred by 3 methods:
 Off-line by using "ICP for Windows" ("Environment → Save Environment As" and
"Environment → Transfer Environment to Programmer")
 On-line by using DLL functions below
 Combination of the both methods above, i.e. multiple environments can be created off-line and then
transferred by DLL function
IMPORTANT: A transferred environment is saved in non-volatile flash memory of the programmer and
automatically reloads after power-up. Don't transfer the same environment multiple times to keep
endurance of internal ICP2 flash (10K cycles minimum, 100K typical)
8.1
IcpSaveEnvironment
See also:
IcpTransferEnvironmentToIcp()
Description:
Prototype:
Parameters:
Creates and saves current workspace into an environment file (extension *.pj2)
int DLL_FUNC IcpSaveEnvironment (const char* aFileName);
aFileName - pointer to char string containing file name
Example:
IcpStartApplication ("icp01.cfg");
IcpInitCom (0, 0, 0);
IcpLoadHexAndSerFile("1.hex","");
IcpSaveEnvironment ("File1.pj2");
IcpEndApplication();
8.2
IcpTransferEnvironmentToIcp
See also:
IcpSaveEnvironment()
Description:
Prototype:
Parameters:
Transfers an environment file (extension *.pj2) to the programmer
int DLL_FUNC IcpTransferEnvironmentToIcp (const char* aFileName);
aFileName - pointer to char string containing file name
Rev: 4.7.3 Jan-2011
Page 8 of 17
ICP Family DLL Description
Example:
IcpTransferEnvironmentToIcp ("File1.pj2");
9 Standalone Operation: RAM Buffer
Every ICP2/ICP2-GANG channel unit has a volatile RAM buffer (256 bytes) which can be used for different
purposes, for example to overwrite non-volatile contents of the environment
9.1
IcpRamUsage
See also:
IcpRamBufWrite() and IcpRamBufRead()
Description:
Prototype:
Parameters:
Communicates with ICP2 and defines functionality of the RAM buffer
int DLL_FUNC IcpRamUsage( int aPmStartAddr, int aPmQuan, int aDmStartAddr,
int aDmQuan, int aUsage )
aPmStartAddr - start address (in bytes) of PM to be overwritten by the RAM buffer
aPmQuan - length of overwritten block (PM) in bytes
aDmStartAddr - start address (in bytes) of DM (EEPROM) to be overwritten by
the RAM buffer
aDmQuan - length of overwritten block (DM) in bytes
aUsage - functionality of RAM buffer according to enum RAM_BUF_USAGE – see ‎14.2.4
Return Value: A) -1: incorrect parameter(s)
B) according to AUTO_ERROR_LEVEL
Note:
This function does not execute immediately changes the programmed unit, it just informs
the ICP2 channel to overwrite PM/DM during programming
Example:
Overwrite 256(dec) bytes of PM buffer starting from address 1000(dec)
IcpRamUsage (1000, 256, 0, 0, RAM_BUF_PM);
9.2
IcpRamBufWrite
See also:
IcpRamUsage() and IcpRamBufRead()
Description:
Prototype:
Parameters:
Writes up to 256 bytes into RAM buffer of ICP2 unit
int DLL_FUNC IcpRamBufWrite(unsigned char *aRamBuf, int aStartAddr, int aQuan)
aRamBuf - pointer to user's buffer to be copied from
aStartAddr-start address of the RAM buffer
aQuan - number of bytes to be written
Return Value: A) -1: incorrect parameter(s)
B) according to AUTO_ERROR_LEVEL
Example:
9.3
Load RAM buffer with a string below
#define OVERWRITE_LEN 20 //20 bytes to be loaded
char MyBuf[] = "ICP2 Programmer";
IcpRamBufWrite(MyBuf, 0, OVERWRITE_LEN);
IcpRamBufRead
See also:
IcpRamUsage() and IcpRamBufWrite()
Description:
Prototype:
Parameters:
Reads up to 256 bytes from RAM buffer of ICP2 unit
int DLL_FUNC IcpRamBufRead(unsigned char *aRamBuf, int aStartAddr, int aQuan)
aRamBuf - pointer to user's buffer to be copied to
aStartAddr-start address of the RAM buffer
aQuan - number of bytes to be read
Rev: 4.7.3 Jan-2011
Page 9 of 17
ICP Family DLL Description
Return Value: A) -1: incorrect parameter(s)
B) according to AUTO_ERROR_LEVEL
Example:
Validate that RAM buffer is loaded as expected
#define OVERWRITE_LEN 20 //20 bytes to be loaded
char MyBuf[] = "ICP2 Programmer";
char MyVerifyBuf[OVERWRITE_LEN];
IcpRamBufWrite(MyBuf, 0, OVERWRITE_LEN);
IcpRamBufRead(MyVerifyBuf, 0, OVERWRITE_LEN);
Compare MyBuf and MyVerifyBuf
10 Standalone Operation: Multiple Environments
Up to 2 environments can be loaded into a single channel of ICP2/ICP2-GANG. Default environment size is
as follows:
- environment 1: 655KByte (may extend to 1MByte is environment 2 is not used)
- environment 2: 390Kbyte. This size is suitable for all devices excluding PIC32 with flash size 512Kbyte
Environment 1 is always selected after power-up for ICP2/ICP2-GANG
10.1 IcpSwitchEnv
Description: Communicates with programmer and simultaneously switches environment for all channels
Prototype:
int DLL_FUNC IcpSwitchEnv (int aEnv);
Parameters: aEnv should be 0 (environment 1) or 1 (environment 2)
Return Value: A) -1: environment number is out of range
B) -2: operation is not supported (ICP-01)
C) according to AUTO_ERROR_LEVEL
Example:
IcpSwitchEnv(1); //switch to environment 1
11 PC-Driven Operation: Access to PC Memory Buffers
Function IcpGetBuffers() allows reading and modification of internal programming buffers in PC-driven mode.
It may be useful for applications that require buffer manipulation without (or in addition to) using hex file.
NOTE: be careful when modifying programming buffers
11.1 IcpGetBuffers
typedef struct { //use members shown in bold italic
int
PmWordSize;
// Program Memory word size
unsigned PmMaxWordVal; // Program Memory maximal word value
int
PmAddrUnit;
// Program Memory address unit
char *PmBuf; int PmSize;
// Program Memory (flash)
char *IdBuf; int IdSize;
// ID Memory
char *DmBuf; int DmSize;
// Data Memory (EEPROM)
char *CmBuf; int CmSize;
// Calibration Memory (not supported)
char *FuBuf; int FuSize;
// Fuses Memory (configuration words)
} iBUFFERS;
Description:
Prototype:
Parameters:
Provides pointer to the internal programming buffers (in PC memory)
void DLL_FUNC IcpGetBuffers (iBUFFERS *aBufs);
pointer to structure iBUFFERS
Rev: 4.7.3 Jan-2011
Page 10 of 17
ICP Family DLL Description
Return Value: none
Example:
iBUFFERS MyBuf;
IcpGetBuffers(&MyBuf);
MyBuf.DmBuf[1]=0x55; //modify buffer for EEPROM programming
MyBuf.DmBuf[2]=0x56; //
IcpDoAction(ACT_PROG,…); //execute PC-driven programming
12 Direct Hardware Control
ICP DLL provides direct access to ICP2/ICP2-GANG hardware. The functions are listed below, for more
details see document "ICP2 - FTM Functions.pdf"
###
1.
2.
3.
4.
5.
6.
7.
Function Name
Icp2AdConv()
Icp2DaVolt ()
Icp2PinState()
Icp2ClockDataComPar()
Icp2SingleClockDataAction()
Icp2MultiClockDataAction()
Icp2SafeOff()
Function Description
Execute A/D Conversion
Set D/A Levels (not pins) for VDD, VPP or VLIM
Set/Read Pin State
Set CLOCK/DATA ("RB6/RB7") Communication Parameters
Execute single CLOCK/DATA Communication
Execute multiple CLOCK/DATA Communications
Turn ICP2 pins to safe state (off)
13 More DLL Functions
File "c_icpexp.h" contains many additional DLL functions (write/read to internal ICP EEPROM, calibration,
security, FTB9 operation, etc). Specify your tasks and contact Softlog Systems for suggestion. Additional
DLL functions can be done upon your request
14 Appendix A: Return Values and Definitions
14.1 Return Values
DLL functions return value according to enum AUTO_ERROR_LEVEL below:
enum AUTO_ERROR_LEVEL { //return values
AUTO_OK
AUTO_DB_ERR
AUTO_COM_ERR
AUTO_VDD_ERR
AUTO_VPP_ERR
AUTO_HEX_ERR
AUTO_SER_ERR
AUTO_VER_ERR
AUTO_ERR_NO_SPACE
AUTO_SAVE_ERR
AUTO_SOCK_ERR
AUTO_I2C_ERR
AUTO_DLL_ERR
AUTO_KEY_ERR
AUTO_CFG_ERR
AUTO_COM_NUM_ERR
AUTO_COM_BUSY_ERR
AUTO_COM_BAUD_ERR
AUTO_COM_NO_OPEN
AUTO_USER_CANCEL
AUTO_IN_PROGRESS
AUTO_BC_ERR
AUTO_OP_NOT_ALLOW
AUTO_FW_INVALID
AUTO_24LC_ADDR_ERR
AUTO_DM_ADDR_ERR
AUTO_FIRM_ERR
AUTO_NO_SUB
AUTO_NO_SUP_KEE
AUTO_NO_SUP_DSPIC
Rev: 4.7.3 Jan-2011
= 0, //operation OK
= 1, //database error
= 2, //communication error
= 3, //Vdd overload error
= 4, //Vpp overload error
= 5, //HEX file loading error
= 6, //serialization file error
= 7, //verification error
= 8, //no space selected
= 9, //file save error
= 10, //socket communication error (obsolete)
= 11, //UUT I2C communication error
= 12, //DLL programming is not supported
= 13, //key generation error
= 14, //config. file error
= 15, //invalid COM number
= 16, //selected COM is busy
= 17, //invalid baud rate
= 18, //can't open COM port
= 19, //user cancel
= 20, //operation in progress
= 21, //blank check error
= 22, //operation not allowed for selected programmer
= 23, //firmware invalid-firmware upgrade needed
= 24, //24LC01 address (offset) is out of range
= 25, //DM range error
= 26, //firmware version error
= 27, //no ICP-SUB PCB
= 28, //no keeloq support
= 29, //no dsPIC support
Page 11 of 17
ICP Family DLL Description
AUTO_ICP2_REQ
AUTO_DEV_ERR
AUTO_PROG_MISMATCH
AUTO_PRJ_INVALID
AUTO_PRJ_DB_FIRM_PC_MIS
AUTO_PRJ_DB_FIRM_AT45_MIS
AUTO_DLL_SUPPORT_REQIURED
AUTO_PRJ_CS
AUTO_STA_IDLE
AUTO_STA_BUSY
AUTO_ENV_ERR
AUTO_PM_RANGE
AUTO_SEC_SUPPORT_REQUIRED
AUTO_SEC_CNT_INTEG
AUTO_SEC_CNT_ZERO
AUTO_SEC_NO_FUNC
AUTO_SEC_PACK_ERR
AUTO_SEC_EEPROM_FAIL
AUTO_SEC_ANTI_SCAN
AUTO_SEC_SEC_ID_CMP
AUTO_SEC_PASSW_CMP
AUTO_SEC_BATCH_CMP
AUTO_SEC_VERS_ERR
AUTO_SEC_UNKNOWN_ERR
AUTO_NO_ROW_ERASE
AUTO_INVALID_PARAM
AUTO_MOVLW_RETLW_CALIB
AUTO_NO_USUAL_ENV_TRAN
AUTO_SEC_BUF_START_ADDR
AUTO_SEC_BUF_END_ADDR
AUTO_SEC_BUF_PAGE_START
AUTO_SEC_BUF_PAGE_SIZE
AUTO_SEC_BUF_NOT_EVEN
AUTO_SEC_BUF_NO_DM
AUTO_SEC_BUF_LAST_PAGE
AUTO_SEC_BUF_NO_16BIT_SUP
AUTO_SEC_BUF_NOT_MODULO_3
AUTO_SEC_EMPTY_MASK
AUTO_TEST_COM_NO_SUPPORT
AUTO_TEST_NACK
AUTO_NO_SUP_P32
AUTO_PIC32_BUSY_OR_DAMAGED
AUTO_PIC32_CP_OR_DAMAGED
AUTO_PIC32_PE_ANSWER
AUTO_PIC32_PE_VERSION
AUTO_SEC_BUF_NO_32BIT_SUP
AUTO_CNT_ZERO
= 30, //ICP2 required
= 31, //device selection error (unspecified error)
= 32, //mismatch between selected and detected programmers
= 33, //Invalid environment
= 34, //mismatch between PC and firmware database
= 35, //mismatch between environment and firmware database
= 36, //obsolete: "GO" pressed on hardware and no DLL/standalone support
= 37, //environment CS error
= 38, //programmer is idle or standalone operation can't be started
= 39, //standalone operation: programmer busy
= 40, //environment file error
= 41, //invalid PM range specified
= 42, //Security support required
= 43, //Future: Security feature: integrity error in counter
= 44, //Future: Security feature: counter = 0
= 45, //Future: Security feature: function does not exist
= 46, //Future: Security feature: packet error
= 47, //Future: Security feature: EEPROM error
= 48, //Future: Security feature: anti-scan activated,
= 49, //Future: Security feature: incorrect Security ID
= 50, //Future: Security feature: incorrect password
= 51, //Future: Security feature: incorrect batch
= 52, //Future: Security feature: version error
= 53, //Future: Security feature: unknown error
= 54, //row erase is not supported
= 55, //invalid parameters
= 56, //no movlw in calibration word
= 57, //Usual environment can't be sent if a secure one inside
= 58, //sec. buf. properties error: incorrect start addr
= 59, //sec. buf. properties error: incorrect end addr
= 60, //sec. buf. properties error: incorrect page start
= 61, //sec. buf. properties error: incorrect page size
= 62, //sec. buf. properties error: length not even
= 63, //sec. buf. properties error: no DM in PIC
= 64, //sec. buf. properties error: last PM page can't be used
= 65, //sec. buf. properties error: no Script 1 for 16-bit devices
= 66, //sec. buf. properties error: length not modulo 3
= 67, //Security feature: empty mask for secure environment
= 68, //ICP2 test command not supported
= 69, //ICP2 test command returns NACK
= 70, //no PIC32 support
= 71, //PIC32 is busy or damaged
= 72, //PIC32 is code protected or damaged
= 73, //PIC32 programming executive: no answer
= 74, //PIC32 programming executive: incorrect version
= 75, //no security support for PIC32
= 76, //non-secure (low-endurance) counter is 0
AUTO_DEMO_ERR
= 101 }; //demo version
14.2 Definitions
14.2.1 Action List
enum ACTION_LIST {
ACT_PROG
ACT_VER
ACT_READ
ACT_BC
ACT_STA_PROG
ACT_STA_GET_RES
ACT_STA_CLR_RES
ACT_STA_START_PROG
};
= 1, //PC-driven programming
= 2, //PC-driven verification
= 3, //PC-driven read
= 4, //PC-driven blank check
= 5, //Standalone programming
= 6, //Standalone: communicate and get latest results
= 7, //Standalone: communicate and clear all latest results
= 8, //Standalone: start standalone programming (NOTE: should be monitored then for completion)
14.2.2 Memory Spaces (PC-driven Operation)
enum MEMORY_SPACES {
PM_SPACE
ID_SPACE
DM_SPACE
CM_SPACE
FU_SPACE
ALL_SPACE
Rev: 4.7.3 Jan-2011
= 0x0001, //Program memory (flash)
= 0x0002, //ID locations
= 0x0004, //Data memory (EEPROM)
= 0x0008, //Calibration memory (not supported)
= 0x0010, //Configuration word
= PM_SPACE | ID_SPACE | DM_SPACE | FU_SPACE, //all spaces
Page 12 of 17
ICP Family DLL Description
LAST_SPACE
};
= 0x0020
14.2.3 Programmer Type and Mode
enum PROG_TYPE {
PROG_ICP01
PROG_ICP2
PROG_GANG4
PROG_GANG4_SINGLECHAN
PROG_PORTABLE
PROG_LAST
};
enum PROG_MODE {
SPM_PCDRIVEN
SPM_STANDALONE
SPM_LAST
};
= 0, //ICP-01
= 1, //ICP2 or ICP2(HC)
= 2, //ICP2-GANG (multichannel)
= 3, //ICP2-GANG (single channel)
= 4, //ICP2-Portable
= 0, //PC-driven mode
= 1, //Standalone mode
14.2.4 Usage of RAM Buffer
enum RAM_BUF_USAGE {
RAM_BUF_NO
RAM_BUF_PM
RAM_BUF_DM
RAM_BUF_PM_DM
RAM_BUF_SEC_COM
};
= 0, //not used (default)
= 1, //override PM
= 2, //override DM (EEPROM)
= 3, //override PM and DM (128 per each, for future use)
= 4 //internal use only: security feature related communication between PC and ICP
14.2.5 Environment Status
enum PRJ_VAL {
prjUNKNOWN
prjLOADING
prjINVALID
prjVALID
};
= 0, //unknown state (for PC only)
= 1, //environment loading/validation in progress
= 2, //invalid environment
= 3, //valid environment
14.2.6 Additional Definitions
See files “fr_exp.h” and “fr_icp2.h” for more definitions
15 Appendix B: Software Examples
Contact Softlog Systems for more examples
15.1 Software Example: PC-Driven Mode, Single Channel
// This example shows how to use ICP2 in PC-driven mode
// Be sure that COM port and other settings in *.cfg file meet your hardware setup
#include "fr_exp.h"
#include "c_icpexp.h"
#define CFG_FILE
#define HEX_FILE
#define SER_FILE
"icp01.cfg"
"hex1.hex"
"ser1.ser"
#define MY_ACTION
#define MEM_SPACE
ACT_PROG
ALL_SPACE
//action = PC-driven programming
//selected operation will apply to all memory spaces
#define PM_USER
#define PM_START
#define PM_END
0
0
0
//0-full PM range, 1-user defined
//not valid if PM_USER=0
//not valid if PM_USER=0
#define DM_USER
#define DM_START
#define DM_END
1
0
0x3F
//1-user defined DM (EEPROM) range
//DM start
//DM end
int FullCycle(void)
{
int ret; //errorcode
Rev: 4.7.3 Jan-2011
Page 13 of 17
ICP Family DLL Description
ret = IcpStartApplication (CFG_FILE);
if(ret)
return ret;
ret = IcpInitCom (0, 0, 0); //init COM from *.cfg file
if(ret) {
IcpEndApplication();
return ret;
}
//At this point application and USB/RS-232 COM port are successfully open
//Load HEX and serialization (SQTP) files (SQTP file is optional, define it as "" if not required)
//-----------------------------------------------------------------------------------------------ret = IcpLoadHexAndSerFile (HEX_FILE, SER_FILE);
if(ret) {
IcpEndApplication(); //it also closes opened COM
return ret;
}
//Enable progress window (optional)
//--------------------------------IcpEnableProgressWindow (1);
//Maximize speed of PC operation (optional)
//----------------------------------------IcpSetSleepOnWaitingRS232(0); //no sleep
//Set DM (EEPROM) memory range (optional)
//--------------------------------------IcpSetDmRange (DM_USER, DM_START, DM_END);
//Execute programming - this operation can be done several times
//-------------------------------------------------------------ret = IcpDoAction ( MY_ACTION,
MEM_SPACE,
PM_USER,
PM_START,
PM_END,
0,
"");
}
IcpEndApplication();
return ret;
}
15.2 Software Example: Standalone Mode, Gang Programming
/* This example shows how to use ICP2-GANG:
1) One-time operation: validate that environments inside ICP2-GANG channels
are OK, otherwise transfer desired environment to the non-volatile memory of the programmer
IMPORTANT: transfer environment as less as possible to keep endurance of internal ICP2 flash (10K
cycles minimum, 100K typical)
2) Multiple operation: GANG programming
Be sure that COM port and other settings in *.cfg file meet your hardware setup
*/
#include "fr_exp.h"
#include "c_icpexp.h"
#define CFG_FILE
#define CHANNEL_QUAN
"icp01.cfg"
4
unsigned short MyChecksum
char MyEnvFile[]
int Res[CHANNEL_QUAN];
= 0xA882;
//example
= "MyEnv.pj2"; //example
//programming results for all GANG channels
//4 GANG channels
int FullCycle(void)
{
int ret;
ret = IcpStartApplication (CFG_FILE);
if(ret)
return ret;
ret = IcpInitCom (0, 0, 0); //init COM from *.cfg file
if(ret) {
Rev: 4.7.3 Jan-2011
Page 14 of 17
ICP Family DLL Description
IcpEndApplication();
return ret;
}
//At this point application and USB/RS-232 COM port are successfully open
//Validate that all channels contain correct environment
//-----------------------------------------------------ret=ValidateEnvironments(); //see function below
Sleep(1000); //delay should be at least 1 sec due to internal "dispatcher" delay in ICP firmware
//Execute programming - this operation can be done several times
//-------------------------------------------------------------if (! ret) {
ret=ProgramGang();//see function below
//<Analyze Res[]
}
IcpEndApplication();
return ret;
}
// Validate that all channels contain correct environment
// (***only after selection of new project/product***)
// ======================================================
int ValidateEnvironments(void)
{
int ch_i;
int err;
int update_env;
ICP_INFO ChannelInfo;
IcpEnableProgressWindow(0); //disable progress window (can be enabled if you wish)
for (ch_i=0; ch_i<CHANNEL_QUAN; ch_i++) //channel-by-channel
{
//Step 1.1: select GANG single channel + PC-driven
//-----------------------------------------------IcpDllSelectProg(PROG_GANG4_SINGLECHAN, SPM_PCDRIVEN, ch_i);
//Step 1.2: Read environment info from a selected channel
//------------------------------------------------------err = IcpDllGetInfoSingle(&ChannelInfo);
//<analyze err>
update_env=0; //prepare
if (ChannelInfo.iValid) //valid structure
{
if (ChannelInfo.iEnvStat==prjINVALID) //invalid environment
update_env=1;
else if (ChannelInfo.iEnvHexFileCs != MyChecksum) //incorrect HEX checksum
update_env=1;
//additional analysis can be added here
}
if (update_env) //environment to be updated
{
//Transfer environment
//-------------------IcpEnableProgressWindow(1); //enable progress window
err = IcpTransferEnvironmentToIcp(MyEnvFile); //transfer environment
//<analyze err>
IcpEnableProgressWindow(0); //disable progress window
}
}
return err;
}
// GANG Programming
// ================
int ProgramGang(void)
{
int ch_i;
int err;
// Step 1: select programmer as GANG + standalone
// ---------------------------------------------IcpDllSelectProg(PROG_GANG4, SPM_STANDALONE, 0);
// Step 2: execute programming
// ---------------------------
Rev: 4.7.3 Jan-2011
Page 15 of 17
ICP Family DLL Description
IcpEnableProgressWindow (1);//enable progress window (optional)
err=IcpDoAction(
ACT_STA_PROG, //aAction
0,
//aMemorySpace (does nothing in standalone programming)
0,
//aPmUserRange (does nothing in standalone programming)
0,
//aPmAddrBeg
(does nothing in standalone programming)
0,
//aPmAddrEnd
(does nothing in standalone programming)
0,
//aSaveResult
"");
//aReadFile
IcpEnableProgressWindow (0);//disable progress window
//Step 2.3: Analyze result
//-----------------------if (err==AUTO_OK)
{
; //do nothing, all channels OK
}
else
{
for (ch_i=0; ch_i<CHANNEL_QUAN; ch_i++)
Res[ch_i]=IcpReadStaResOneCh(ch_i); //read and save all results
}
return err;
}
15.3 More Software Examples
Contact Softlog Systems for more software examples (GANG programming with RAM buffer, other PC
operations during programming, final test functions, etc)
Rev: 4.7.3 Jan-2011
Page 16 of 17
ICP Family DLL Description
16 Technical Assistance
You may contact Softlog Systems for technical assistance by calling, sending a fax or e-mail. To help us give
you quick and accurate assistance, please provide the following information:





Software version number, firmware version number and product serial number (if available). This
information is displayed at the program start
Detailed description of the problem you are experiencing
Error messages (if any)
Microcontroller part number (if device-related)
Send us your "icp01.cfg" file
17 Warranty
Softlog Systems (2006) Ltd. warrants this product against defects in materials and workmanship for a period
of 1 (one) year. This warranty will not cover programmers that, in the opinion of Softlog Systems, have been
damaged due to abuse, improper use, disassembly, replacement of parts or attempted repair by anyone
other than an authorized Softlog Systems service technician.
This product must be returned to the supplier for warranty service within the stated period. The buyer shall
pay all shipping costs and other charges or assessments for the product by the supplier.
Softlog Systems shall not be liable for any indirect, incidental, or consequential damages, regardless of
whether liability is based upon breach of warranty, negligence, strict liability in tort, or any other theory,
Softlog Systems will never be liable in an amount greater than the purchase price of the products described
by this express warranty. No agent, distributor, salesperson, or wholesale or retail dealer has the authority to
bind Softlog Systems to any other affirmation, representation, or warranty concerning these goods.
18 Contact
Softlog Systems (2006) Ltd.
Rojanski 18 St. Rishon-Letzion 75070 Israel
Phone:
Fax:
Web:
E-mail:
972-3-9515359
972-3-9527520
www.softlog.com
[email protected], [email protected]
19 Copyright Notice
Windows is a registered trademark of Microsoft Corporation. Microchip, MPLAB, PIC and dsPIC are
registered trademarks of Microchip Technology Incorporated.
Rev: 4.7.3 Jan-2011
Page 17 of 17