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