...
| Page Tree | ||||
|---|---|---|---|---|
|
| Anchor |
|---|
...
These functions operate on meta-data within the Multi API-DLL and help manage the underlying API-DLL instances. These functions do not directly program target devices. Use these functions to initialize the desired number of FPAs, selected all or one FPA(s), read FPA serial numbers, or clean-up resources used by Elprotronic’s DLLs.
Once the desired FPAs have been successfully opened, use Generic Functions (Section 3.2) to initialize the FPAs, and configure them for the target device(s) being programmed.
...
General Description
Multi API-DLL scans USB ports for connected FPAs listed in the setup file, or input string. When an FPA listed in the setup file is found, the corresponding API-DLL is copied on disk if necessary, and loaded. F Initialization should be called for each FPA after this function succeeds.
IMPORTANT
Do not invoke F Check FPA access after this function has assigned FPAs to USB ports. To check simple communi- cation with FPA, use the F Get FPA SN function.
Syntax
INT_X F_OpenInstancesAndFPAs( char * FileName )
Input
char * FileName : path to setup file, or list of serial numbers.
38
Setup file: Should contain a list of FPA and SN pairs.
FPA-1 20090123
FPA-3 20090234
--or--
FPA-1 20090123
FPA-3 * //any serial number (can only be done at last line)
--INVALID--
FPA-1 * //this line will be read FPA-3 * //this line will be ignored
List of serial numbers: A string with serial numbers, automatically assigned to FPA-1, 2, 3, etc.
input string: "*# 20090123 20090346" translates to:
FPA-1 20090123
FPA-2 20090345
input string: "*# *" translates to:
FPA-1 *
In both cases, for the setup file and the input string, if a specified FPA is missing then it will not affect subsequent entries. Therefore, a setup file with these contents:
...
FPA-1
...
20090123
...
FPA-2
...
20090346
...
FPA-3
...
20090222
...
FPA-4
...
20090245
and with FPA-3 missing (not connected, etc.) will initialize the Multi API-DLL to:
...
FPA-1
...
20090123
...
FPA-2
...
20090346
...
FPA-3
...
empty
...
FPA-4
...
20090245
Output
INT X : number of instances opened successfully
...
General Description
All FPAs terminate communication with target devices and close target devices according to con- figuration settings (power setting, adapter line states, etc.). Finally, the USB connections to the FPAs are terminated and API-DLL instances are freed. The Multi API-DLL can now be used to open a new set of FPAs using the function F OpenInstancesAndFPAs.
Syntax
INT_X F_CloseInstances ( void );
Input
none.
Output
INT X : success
TRUE (1)
...
General Description
Select desired FPA index to perform specific tasks (access specific API-DLL instance).
Syntax
INT_X F_Set_FPA_index ( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64, or 0 for all
Output
INT X : success or error
TRUE (1), used FPA index is valid
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
IMPORTANT
Other functions that try to access FPAs will also return FPA INVALID NO if this function was not called with a proper parameter.
...
General Description
Get current FPA index.
Syntax
BYTE F_Get_FPA_index( void );
Input
none.
Output
BYTE : current FPA index as entered using F Set FPA index
...
General Description
Get current FPA index and check if index is valid. A valid index corresponds to an individual FPA that has been opened with F OpenInstancesAndFPAs. If FPA index was set to 0 (all), then this function will only return 0, even if no FPAs are open. Does not indicate whether FPA index is enabled or disabled.
Syntax
INT_X F_Check_FPA_index ( void );
Input
none.
Output
INT X : current fpa index if valid
current FPA index as entered using F Set FPA index if selected FPA has been opened with F OpenInstancesAndFPAs
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Enable desired FPA index to accept commands. An FPA index is enabled by default. A disabled FPA index will ignore commands when the FPA index is set to it, or 0 (all FPAs).
Syntax
void F_Enable_FPA_index ( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64
Output
none.
...
General Description
Disable desired FPA index to ignore commands. An FPA index is enabled by default. A disabled FPA index will ignore commands when the FPA index is set to it, or 0 (all FPAs).
Syntax
void F_Disable_FPA_index ( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64
Output
none.
...
General Description
Return value from the last function call issued to the specified FPA (API-DLL instance). This function is useful when multiple FPAs are being programmed using FPA index 0 (all), but the return value was not the same for all FPAs (i.e. 4 FPAs succeeded, 1 FPA failed). When the return value is not the same for all FPAs then, then the actual return value from the Multi API- DLL will be FPA UNMATCHED RESULTS. To find out per FPA return values, select each FPA index individually using F Set FPA index, and call F LastStatus for each index.
Syntax
INT_X F_LastStatus ( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64.
Output
INT X : Last return value from the selected FPA (API-DLL instance).
INT X type return value from last function call on selected FPA
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Get Multi API-DLL software version number.
Syntax
INT_X F_Multi_DLLTypeVer( void );
Input
none.
Output
INT X : (DLL ID) — (0x0FFF & Version)
DLL ID = 0x06000, FlashPro430
DLL ID = 0x07000, GangPro430
DLL ID = 0x08000, FlashPro-CC
DLL ID = 0x09000, GangPro-CC
DLL ID = 0x0C000, FlashPro2000
DLL ID = 0x0D000, GangPro2000
DLL ID = 0x10000, FlashPro-ARM
DLL ID = 0x11000, GangPro-ARM
Version = 0x0xyz, version x.yz (i.e. 0x0190 = v 1.90)
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Get serial number (SN) of FPA assigned to specified index.
Syntax
INT_X F_Get_FPA_SN ( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64
Output
INT X : serial number
SN of selected FPA
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Get detailed information of FPA assigned to specified index.
Syntax
INT_X F_Get_FPA_Label ( BYTE fpa, BYTE *label );
Input
BYTE fpa : desired FPA index, 1 to 64.
BYTE *label : pointer to byte array, of at least FPA LABEL SIZE (80 bytes)
Output
INT X : serial number, hardware ID, meta-data
updated FPA LABEL structure pointed to by label input parameter
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
#define FPA_LABEL_SIZE 80
#define ADAPTER_HARDWARE_PN_SIZE 16
#define ADAPTER_DESCRIPTION_SIZE 32
union FPA_LABEL
{
BYTE bytes[ FPA_LABEL_SIZE ];
struct
{
long SN;
BYTE hardware_ID;
BYTE hardware_SubID;
BYTE full_access;
BYTE Interface_Type;
BYTE Valid_access_key; BYTE spare3;
BYTE spare4; BYTE spare5; BYTE spare6; BYTE spare7; BYTE spare8; BYTE spare9;
char adapter_hardware_PN[ ADAPTER_HARDWARE_PN_SIZE ]; char adapter_description[ ADAPTER_DESCRIPTION_SIZE ];
}x;
};
...
General Description
Get internal progress counter value for operations done inside Encapsulated Functions (Section 3.4). When used in conjunction with F GetLastOpCode it allows the user application to keep track of progress in the same way that the GangPro-ARM GUI does.
Will return value between 0 and 100 for current sub-operation being performed inside en- capsulated function. Depending on the complexity of the encapsulated function, the number of
sub-operations will vary. Use F GetLastOpCode to get currently running sub-operation opcode. When transitioning from one sub-operation that reached a progress value of 100, to another sub- operation, the progress value will restart at 0. This will repeat until the last sub-operation upon which the progress value will remain at 100. A new invocation of an encapsulated function will restart the progress value at 0.
This function is thread-safe, therefore it can be called while the Multi API-DLL is busy, for ex- ample running F AutoProgram. Intended usage is to call an encapsulated function with one thread, and repeatedly call this function and F GetLastOpCode with another thread. When simultane- ously programming using multiple FPAs (fpa index set to 0 (ALL FPAs), the thread monitoring progress can iterate different input parameters (fpa=1, fpa=2, fpa=3, etc.) to monitor the progress of each FPA individually. This function cannot be called with parameter 0 (ALL FPAs).
Syntax
INT_X MSPPRG_API F_GetProgressBar( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64.
Output
INT X : progress indicator
value between 0 and 100
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
Example
Refer to GetLastOpCode.
...
General Description
Read internal opcode value for sub-operations done inside Encapsulated Functions (Section 3.4). When used in conjunction with F GetProgressBar it allows the user application to keep track of progress in the same way that the GangPro-ARM GUI does.
Will return opcode for current sub-operation being performed inside encapsulated function. Depending on the complexity of the encapsulated function, the number of sub-operations will vary. Use F GetProgressBar to get progress value between 0 and 100, of currently running sub- operation. When transitioning from one sub-operation that reached a progress value of 100, to
another sub-operation, the progress value will restart at 0 and the opcode will be set to the new sub-operation, currently being run. This will repeat until the last sub-operation upon which the opcode will not change. A new invocation of an encapsulated function will reset the opcode to the first sub-operation of the new encapsulated function.
This function is thread-safe, therefore it can be called while the Multi API-DLL is busy, for ex- ample running F AutoProgram. Intended usage is to call an encapsulated function with one thread, and repeatedly call this function and F GetProgressBar with another thread. When simultaneously programming using multiple FPAs (fpa index set to 0 (ALL FPAs), the thread monitoring progress can iterate different input parameters (fpa=1, fpa=2, fpa=3, etc.) to monitor the progress of each FPA individually. This function cannot be called with parameter 0 (ALL FPAs).
Syntax
INT_X MSPPRG_API F_GetLastOpCode( BYTE fpa );
Input
BYTE fpa : desired FPA index, 1 to 64.
Output
INT X : opcode of currently running sub-operation
PROG OPCODE VERIFY ACCESS (1) : FPA is attempting to perform action described in F Verify Access to MCU.
•
PROG OPCODE FLASH ERASE (2) : FPA is attempting to perform action described in F Memory Erase.
•
PROG OPCODE FLASH BLANK CHECK (3) : FPA is attempting to perform action de- scribed in F Memory Blank Check.
•
PROG OPCODE FLASH SELECTED BLANK CHECK (4) : FPA is attempting to perform action described in F Memory Blank Check when a subset of the memory space is selected in configuration settings.
•
PROG OPCODE FLASH WRITE (5) : FPA is attempting to perform action described in F Memory Write.
•
PROG OPCODE FLASH VERIFY (6) : FPA is attempting to perform action described in F Memory Verify.
•
PROG OPCODE FLASH READ (7) : FPA is attempting to perform action described in F Memory Read.
•
PROG OPCODE LOCK MCU (8) : FPA is attempting to perform action described in F Lock MCU.
•
PROG OPCODE UNLOCK MCU (9) : FPA is attempting to perform action described in F Clear Locked Device.
•
PROG OPCODE START APP (10) : FPA is attempting to run application programmed onto target device (if enabled to be ran after F AutoProgram in configuration settings).
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
Example
void ProgDemoDlg::UpdateProgress()
{
//This function works a bit different than all the others.
//Usually the Multi-API DLL is not thread safe and
//only one thread can enter the Multi-API DLL.
//This function is thread-safe because it is read-only. FPA index != 0. if(fpa == 0)
{
//You can average out the results here,
//or do separate bars per FPA.
//For AutoProgram the progress bar will go from 0 to 100 many
//times during one run because of sub-opcodes. return;
}
INT_X progValue = F_GetProgressBar(fpa); prog->SetPos(progValue);
INT_X lastOpCode = F_GetLastOpCode(fpa); CString opCodeUpdate = "Unknown"; switch(lastOpCode)
{
case PROG_OPCODE_VERIFY_ACCESS:
opCodeUpdate = "Verify Access To MCU"; break;
case PROG_OPCODE_FLASH_ERASE:
opCodeUpdate = "Flash Erase"; break;
case PROG_OPCODE_FLASH_BLANK_CHECK:
opCodeUpdate = "Flash Blank Check"; break;
case PROG_OPCODE_FLASH_SELECTED_BLANK_CHECK:
opCodeUpdate = "Selected Memory Blank Check"; break;
case PROG_OPCODE_FLASH_WRITE:
opCodeUpdate = "Flash Write"; break;
case PROG_OPCODE_FLASH_VERIFY:
opCodeUpdate = "Flash Verify"; break;
case PROG_OPCODE_FLASH_READ:
opCodeUpdate = "Flash Read"; break;
case PROG_OPCODE_LOCK_MCU:
opCodeUpdate = "Lock MCU"; break;
case PROG_OPCODE_UNLOCK_MCU:
opCodeUpdate = "Unlock MCU"; break;
case PROG_OPCODE_START_APP:
opCodeUpdate = "Start Application"; break;
}
CString currentOpCode = ""; GetDlgItemText(IDC_OPCODE, currentOpCode);
//Don’t update if it’s the same text (prevents flashing) if(currentOpCode.Compare(opCodeUpdate) != 0)
SetDlgItemText(IDC_OPCODE, opCodeUpdate);
}
...
General Description
Activate tracing for subsequent calls to the Multi API-DLL. Log is saved in DLLtrace.txt located in the Multi API-DLL directory. When activated, records all API-DLL function calls from the application software invoked via the Multi API-DLL. The DLLtrace.txt is overwritten for each new session.
Syntax
void F_Trace_ON( void );
Input
none.
Output
none.
...
Syntax
void F_Trace_OFF( void );
Input
none.
Output
none.
...
Having correctly configured the top-level Multi API-DLL using Multi API-DLL Functions (Section 3.1), the functions in this section can be used to initialize and configure each FPA individually (and it’s API-DLL instance).
Generic functions read and write the API-DLL’s configuration, access status messages and can instruct the FPA to power or reset the target device. The functions described in this section require that each FPA already be opened using F OpenInstancesAndFPAs.
After the following functions have been used to configure each FPA correctly for its target device, use Data Buffer Functions (Section 3.3) to determine what code should be written during programming. Finally, Encapsulated functions can perform the process of programming, writing, erasing, verifying, etc., according to the aforementioned settings.
...
General Description
Initialize FPA after it has been successfully opened using F OpenInstancesAndFPAs. F Initialization performs the following tasks:
all internal data is cleared and set to default values,
USB driver is initialized if has not been initialized before.
Select which FPA to initialize, using the function F Set FPA index with desired parameter (0- all, 1-64 for individual FPA). After successful initialization, call F ConfigFileLoad to read settings from file, or configure settings manually using the function F Set Config Value By Name.
For backwards compatibility, F Initialization will call F OpenInstancesAndFPAs(*# *) if no instances are currently opened, and perform initialization on FPA 1. If F OpenInstancesAdFPAs was already invoked successfully then initialization is performed on the selected FPA index from the function F Set FPA index.
Default config file used to perform initialization is config.ini (Use F Use Config INI(FALSE) to disable automatic load of config.ini).
Syntax
INT_X F_Initialization( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
4 : Programming adapter not detected
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Configure F Initialization to use (default) or skip config.ini file. When skipping config.ini it is necessary to use ConfigFileLoad or F Set Config Value By Name functions to configure the adapter.
Syntax
INT_X F_Use_Config_INI(BYTE use);
Input
BYTE use : 1 to use config.ini, 0 to skip
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Iterate over configuration parameter names, starting from index 0. Increase index until return is null character. Will return a pointer to a character array with name of parameter or null character once index is too high.
Requires the target FPA to be opened using F OpenInstancesAndFPAs and initialized using F Initialization.
Syntax
char * F_Get_Config_Name_List( INT_X index );
Input
INT X : configuration parameter index, starting from zero. Increment until return value is null character.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
char * : configuration parameter name
a valid character array pointer containing name of configuration parameter (do not free after use)
•
null character : end of parameter list
”” : invalid fpa index, cannot be zero
...
General Description
Access the current FPA’s configuration. Use F Get Config Name List to get configuration param- eter names, then use them as input to this function. Select input type to validate name, and get current, minimum, maximum, and default values.
Because normal return values from this function can be any value, from 0 to 0xFFFFFFFF, it is important to pick a correct fpa index (use F Check FPA index to validate) and validate the configuration parameter name first (using CONFSEL VALIDATE), before retrieving the current, minimum, maximum or default values. Unless all FPAs are to be configured identically, avoid using FPA index 0 to prevent confusion in results (when results don’t match using FPA index 0 (all FPAs) the result is simply FPA UNMATCHED RESULTS (-1)).
Requires the target FPA to be opened using F OpenInstancesAndFPAs and initialized using F Initialization.
Syntax
unsigned int F_Get_Config_Value_By_Name(char *name, INT_X type);
Input
char * name : parameter name INT X type : select action
CONFSEL VALIDATE (0) : returns TRUE if name was found in configuration list
CONFSEL VALUE (1) : returns current value of configuration parameter
CONFSEL MIN (2) : returns minimum value that this configuration parameter can have
CONFSEL MAX (3) : returns maximum value that this configuration parameter can have
CONFSEL DEFAULT (4) : returns default value for this configuration parameter if not set by user/file
•
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
unsigned int : depends on input
FALSE (0) : failed name validation (CONFSEL VALIDATE)
TRUE (1) : successful name validation (CONFSEL VALIDATE)
any : actual parameter value, minimum and maximum bounds, and default value if not set by user/file (CONFSEL VALUE, CONFSEL MIN, CONFSEL MAX, CONFSEL DEFAULT)
•
-1 or 0xFFFFFFFF : name not found (avoid this by using CONFSEL VALIDATE first)
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus(avoid this by not using FPA index 0)
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range(avoid this by using F Check FPA index first)
•
...
General Description
Set the current FPA’s configuration. Use F Get Config Name List to get configuration param- eter names, then use them as input to this function. New value for configuration parameter will be trimmed by minimum and maximum values allowed for this parameter. If not initial- ized, this parameter will have a default value. Double check parameters after configuration using F Get Config Value By Name.
Requires the target FPA to be opened using F OpenInstancesAndFPAs and initialized using F Initialization.
Syntax
INT_X F_Set_Config_Value_By_Name(char *name, unsigned int newValue);
Input
char * name : parameter name
unsigned int newValue : assign new configuration parameter value (will be trimmed by min/max if necessary)
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : parameter name not found
TRUE (1) : name found and parameter value changed
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Get information about selected microcontroller.
Syntax
INT_X F_Get_Device_Info( INT_X index );
Input
INT X : select type of information to receive
DEVICE NAME (0) : get character 0, increase index up to 19 to get last character
DEVICE VENDOR INDEX (30) : Vendor Index (superset of all supported MCUs, i.e. com- pany name)
•
DEVICE FAMILY INDEX (20) : Family Index (subset of MCU vendor, index 30)
DEVICE GROUP INDEX (21) : Group Index (subset of MCU family, index 20)
DEVICE NAME INDEX (22) : Name Index (subset of MCU group, index 21)
DEVICE GROUP (23) : Obsolete
DEVICE FLASH START ADDR (24) : Flash Start Address, i.e. 0x00000
DEVICE FLASH END ADDR (25) : Flash End Address, i.e. 0x1FFFF
DEVICE OTP START ADDR (26) : OTP Start Address, i.e. 0x400FE1E0
DEVICE OTP END ADDR (27) : OTP End Address, i.e. 0x400FE1EF
DEVICE RAM START ADDR (28) : RAM Start Address, i.e. 0x20000000
DEVICE RAM END ADDR (29) : RAM Start Address, i.e. 0x20010000 Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
INT X : value dependent on input parameter
any : based on input parameter
-1 (0xFFFFFFFF) : invalid input parameter
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Set target microcontroller name. A list of acceptable names can be obtained using the functions F Set MCU Family Group and F Get MCU Name list.
Syntax
INT_X F_Set_MCU_Name( char *MCU_name );
Input
char * : Exact name of target microcontroller.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : microcontroller index if successful
microcontroller index if input name was found and set, index is greater than or equal to zero (0)
•
-1 (0xFFFFFFFF) : name not found (avoid by getting list of proper names using F Get MCU Name list)
•
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Obtain a list of supported vendors, families, groups, and MCUs for the specified FPA. Use this function in conjunction with F Set MCU Family Group to get all supported MCU names. First obtain the names of supported vendors, then select one vendor. Then, for the selected vendor obtain the names of supported families, then select one family, etc.
The MCU names obtained from this function are the exact names used to configure the FPA using the function F Set MCU Name for the target device you want to program.
Syntax
char * F_Get_MCU_Name_list( INT_X type, INT_X index );
Input
INT X type : specify which list to get names from
MCU VENDOR LIST (0) : get name of vendors enabled on this FPA
MCU FAMILY LIST (1) : get name of MCU families supported from the selected vendor
MCU GROUP LIST (2) : get name of MCU groups supported from the selected MCU family
MCU NAME LIST (3) : get name of MCU supported from the selected MCU group INT X index : list index starting from zero, increment until returned string is null character.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
char * : Name of vendor, family, group, or MCU for the given index.
valid name : if correct parameters provided
”” : incorrect FPA index provided (avoid using F Check FPA index)
Example
Refer to F Set MCU Family Group.
...
General Description
Select vendor, family, group and MCU index. Use this function in conjunction with F Get MCU Name list to get all supported MCU names. First obtain the names of supported vendors, then select one vendor. Then, for the selected vendor obtain the names of supported families, then select one family, etc.
Use MCU names to configure the FPA using the function F Set MCU Name. Use this function only to obtain the list of supported MCU names, not to configure the FPA. When NEW MCUs are supported then these indices will change.
Syntax
INT_X F_Set_MCU_Family_Group( INT_X type, INT_X index );
Input
INT X type : specify which list to set index for
MCU VENDOR LIST (0) : set vendor index on this FPA
MCU FAMILY LIST (1) : set family index from the selected vendor
MCU GROUP LIST (2) : set group index from selected MCU family
MCU NAME LIST (3) : set MCU index from selected MCU group (use actual INT X index : set list index
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : index parameter out of range
TRUE (1) : index parameter set correctly
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
Example
//C++ and C# are available in the installation package
//that implement this code
//Example from demo included in installation package
//Select one FPA index to perform this sequence on.
//If all FPA are the same then iterating over other FPA indices is not necessary.
//Iterate over supported vendors, then select vendor zero in this case
//Pull-down menu in demo allows user to change selected vendor index void ProgDemoDlg::Init_MCU_Vendor_ComboBox( void )
{
int k;
char *name;
SelMCU_Vendor->ResetContent();//Reset list of vendors k = 0;
Vendor_list_size = 0; do
{
//----------------------------------------------------
name = F_Get_MCU_Name_list( MCU_VENDOR_LIST, k );//get name of vendor at index k if( strlen( name ) == 0 ) break; //reached end of list of vendors
//----------------------------------------------------
if(SelMCU_Vendor)
{
//----------------------------------------------------
SelMCU_Vendor->AddString( name ); //add newly acquired vendor name to GUI list
//----------------------------------------------------
Vendor_list_size++;
}
k++;
}while(1);
//Select vendor zero in demo GUI (will not affect DLL yet) SelMCU_Vendor->SetCurSel(0);
//Select chosen vendor and read supported MCU families OnCbnSelchangeMcuVendor();
}
//Initialize list of supported families for selected vendor void ProgDemoDlg::OnCbnSelchangeMcuVendor( void )
{
Vendor_list_index = SelMCU_Vendor->GetCurSel();
//----------------------------------------------------
//Set vendor to selected index (during initialization this is usually zero) F_Set_MCU_Family_Group( MCU_VENDOR_LIST, Vendor_list_index );
//----------------------------------------------------
Init_MCU_Family_ComboBox();
}
//Iterate over supported families for selected vendor, then select family zero in this case
//Pull-down menu in demo allows user to change selected family index void ProgDemoDlg::Init_MCU_Family_ComboBox( void )
{
int k;
char *name;
SelMCU_Family->ResetContent(); k = 0;
Family_list_size = 0; do
{
//----------------------------------------------------
name = F_Get_MCU_Name_list( MCU_FAMILY_LIST, k ); //get name of family at index k if( strlen( name ) == 0 ) break; //reached end of list of families
//----------------------------------------------------
if(SelMCU_Family)
{
//----------------------------------------------------
SelMCU_Family->AddString( name ); //add newly acquired family name to GUI list
//----------------------------------------------------
Family_list_size++;
}
k++;
}while(1);
//Select family zero in demo GUI (will not affect DLL yet) SelMCU_Family->SetCurSel(0);
//Select chosen family and read supported MCU groups OnCbnSelchangeMcuFamily();
}
//Initialize list of supported groups for selected family void ProgDemoDlg::OnCbnSelchangeMcuFamily( void )
{
Family_list_index = SelMCU_Family->GetCurSel();
//----------------------------------------------------
//Set family to selected index (during initialization this is usually zero) F_Set_MCU_Family_Group( MCU_FAMILY_LIST, Family_list_index );
//----------------------------------------------------
Init_MCU_Group_ComboBox();
}
//Iterate over supported groups for selected family, then select group zero in this case
//Pull-down menu in demo allows user to change selected group index void ProgDemoDlg::Init_MCU_Group_ComboBox( void )
{
int k;
char *name;
SelMCU_Group->ResetContent(); MCU_Group_list_size = 0;
k = 0;
do
{
//----------------------------------------------------
name = F_Get_MCU_Name_list( MCU_GROUP_LIST, k ); //get name of group at index k if( strlen( name ) == 0 ) break; //reached end of list of groups
//----------------------------------------------------
if(SelMCU_Group)
{
//----------------------------------------------------
SelMCU_Group->AddString( name ); //add newly acquired group name to GUI list
//----------------------------------------------------
MCU_Group_list_size++;
}
k++;
}while(1);
//Select group zero in demo GUI (will not affect DLL yet) SelMCU_Group->SetCurSel(0);
//Select chosen group and read supported MCUs OnCbnSelchangeMcuGroup();
}
//Initialize list of supported MCUs for selected group void ProgDemoDlg::OnCbnSelchangeMcuGroup( void )
{
MCU_Group_list_index = SelMCU_Group->GetCurSel();
//----------------------------------------------------
//Set group to selected index (during initialization this is usually zero) F_Set_MCU_Family_Group( MCU_GROUP_LIST, MCU_Group_list_index );
//----------------------------------------------------
Init_MCU_List_ComboBox();
}
//Iterate over supported MCUs for selected group, then select MCU zero in this case
//Pull-down menu in demo allows user to change selected MCU index void ProgDemoDlg::Init_MCU_List_ComboBox( void )
{
int k;
char *name;
SelMCU_List->ResetContent(); MCU_Name_list_size = 0;
k = 0;
do
{
//----------------------------------------------------
name = F_Get_MCU_Name_list( MCU_NAME_LIST, k ); //get name of MCU at index k if( strlen( name ) == 0 ) break; //reached end of list of MCUs
//----------------------------------------------------
if(SelMCU_List)
{
//----------------------------------------------------
SelMCU_List->AddString( name ); //add newly acquired MCU name to GUI list
//----------------------------------------------------
MCU_Name_list_size++;
}
k++;
}while(1);
//Select MCU zero in demo GUI (will not affect DLL yet) SelMCU_List->SetCurSel(0);
//At this point all the MCU names for selected vendor, family, and group have been read.
//Iterate over all vendors, families, groups, and MCU lists to obtain names of all
//supported MCUs. Use the actual MCU names to call function F_Set_MCU_name and configure
//the FPA.
//NOTE: DO NOT RELY ON MCU INDEX TO CONFIGURE ADAPTER, USE ACTUAL MCU NAMES.
//Although calling F_Set_MCU_Family_Group( MCU_NAME_LIST, MCU_index ) will work at this
//point to select the correct MCU the input MCU_index is only referring to the desired
//MCU if vendor, family, and group index are also set correctly. An MCU_index of 5 will
//be two different MCUs depending on the aforementioned parameters. Most importantly,
//when NEW MCUs are added to the list of supported MCUs, these indices will no longer
//be referring to the same MCUs.
//For this reason, it is preferable to use actual MCU names to configure the FPA,
//because it will be more reliable.
}
...
General Description
Get the last report message from the programmer. When any of the DLL functions are called, an output message is usually created. The GUI uses these messages to print to the dialog box. The user application can use these messages to populate its own dialog box. The last report message can be read by user application using these functions.
When these functions are called, then a report message of up to RE- PORT MESSAGE MAX SIZE characters is copied to the character array passed as input parameter, or in the case of the latter function, a pointer to a statically allocated character array is returned with the output message text.
Calling F ReportMessage clears the message buffer. If F ReportMessage is not called, then the report message will collect all reported information up to REPORT MESSAGE MAX SIZE most recent characters.
Syntax
void F_ReportMessage( char * text ); char* F_Report_Message( void );
Input
char * text : F ReportMessage, allocated text buffer of up to REPORT MESSAGE MAX SIZE (2000) characters.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
char * : F Report Message, pointer to statically allocated character array containing output mes- sage text
...
General Description
Get one character from the report message buffer.
Syntax
char F_GetReportMessageChar( INT_X index );
Input
INT X index : character index, starting from 0 to REPORT MESSAGE MAX SIZE - 1. Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
char : character from report message buffer.
...
General Description
Get information about DLL software type and version. This function returns integer number with DLL ID and software revision version and copies a text message to the report message buffer about DLL ID and software revision. Text content can read using F ReportMessage, F Report Message, or F GetReportMessageChar functions.
Syntax
INT_X F_DLLTypeVer( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.
Output
INT X : (DLL ID) — (0x0FFF & Version)
DLL ID = 0x1000, FlashPro430 - Parallel Port
DLL ID = 0x2000, FlashPro430 - USB
DLL ID = 0x3000, GangPro430 - USB
DLL ID = 0x4000, FlashPro-CC - USB
DLL ID = 0x5000, GangPro-CC - USB
DLL ID = 0xA000, FlashPro2000 - USB
DLL ID = 0xB000, GangPro2000 - USB
DLL ID = 0xE000, FlashPro-ARM - USB
DLL ID = 0xF000, GangPro-ARM - USB
Version = 0x0xyz, version x.yz (i.e. 0x0190 = v 1.90)
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Modify programmer’s configuration according to data taken from specified configuration file. This setup will override previous values and leave omitted parameters untouched. When loaded for the first time, unspecified configuration parameters take on default values as given by F Get Config Value By Name. When calling this function multiple times with different config- uration files, make sure to specify all relevant configuration parameters.
A configuration file can be created using the FlashPro GUI software, or use the functions F Get Config Name List, F Get Config Value By Name to extract a list of configuration names and values. The F Set Config Value By Name function can be used to set configuration parameters instead of F ConfigFileLoad.
Requires the target FPA to be opened using F OpenInstancesAndFPAs and initialized using F Initialization.
Syntax
INT_X F_ConfigFileLoad( char * filename );
Input
char * filename : path to configuration file including filename and extension
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS OPEN FILE ERROR (535) : could not open file
STATUS CORRUPT CONFIG ERROR (554) : malformed configuration file (missing header, etc.)
•
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Enable power from FPA to target device. For this function to have its desired effect, configuration settings PowerFromFpaEn must be set to 1. If PowerFromFpaEn is set to 0, then power from FPA is always off regardless of this function’s input parameter.
Syntax
INT X F Power Target( INT X OnOff );
Input
INT X : power setting
FALSE (0) : power off
TRUE (1) : power on
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Generate short reset pulse on target device’s reset line. The length of the reset pulse can be selected using configuration options. The ResetTimeIndex is used to select pre-set times, or for custom setup select the last index and specify ResetPulseTime, and ResetIdleTime.
Syntax
INT_X F_Reset_Target( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Get Vcc in millivolts as read from target device.
Syntax
INT_X F_Get_Targets_Vcc( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : returns target voltage in millivolts
value of zero or greater : voltage in millivolts
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Set state of the Reset, Vcc and JTAG lines after programming is finished.
Syntax
INT_X F_Set_fpa_io_state( BYTE jtag, BYTE reset, BYTE VccOn )
Input
BYTE jtag : set JTAG lines (TMS, TCK, TDI)
DEFAULT JTAG 3ST (0) : JTAG lines set to tri-state
DEFAULT JTAG HI (1) : JTAG lines set to Vcc
DEFAULT JTAG LO (2) : JTAG lines set to GND BYTE reset : set reset line
0 : reset line set to GND
1 : reset line set to Vcc
BYTE VccOn : set Vcc line from adapter
0 : set to tri-state
1 : set to configured Vcc (configuration parameter VccFromFPAin mV)
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Will return the segment/sector size for memory region that contains given address. This func- tion will access the FPA’s meta-data for the target device specified in configuration options. No communication with target device actually takes place.
Syntax
INT_X F_Get_Sector_Size( INT_X address );
Input
INT X address : address contained by segment/sector
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : address out of range
positive number : actual sector size
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus(avoid this by not using FPA index 0)
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range(avoid this by using F Check FPA index first)
•
...
Having setup the Multi API-DLL and API-DLL instances for the correct target devices using functions from previous sections (Sections 3.1 and 3.2). Use the functions in this section to specify what code should be written by each FPA to their target device.
All data coming to and from the target device is saved in temporary buffers (see Figure 1.2) located inside each API-DLL instance. In summary, these buffers are the Code Data Buffer, Write Data Buffer, and Read Data Buffer. During normal programming using Encapsulated Functions, such as F AutoProgram (Section 3.4), the Code Data Buffer is used to program the target device. For custom modifications the Write Data Buffer can be used to write to the target device with- out disturbing the Code Data Buffer using Sequential Functions, such as F Copy Buffer to Flash (Section 3.5).
The Read Data Buffer is used for reading from the target device by the F Copy Flash to Buffer and F Memory Read functions, the contents of which can be accessed using F Get Byte from Buffer.
...
General Description
Read code from file and store in internal FPA buffer to be used in programming. Only code data that fits within the target MCUs memory space will be read, and the rest will be discarded. Therefore, it is necessary to configure the FPA for the correct MCU first, then load the code file. Unspecified locations within the code file are set to the target MCU’s default empty value (for most MCUs it is 0xFF, for some it is 0x00).
Syntax
INT_X F_ReadCodeFile( char * FileName )
Input
char * FileName : path to code file including filename and extension
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS OPEN FILE ERROR (535): could not open file
STATUS FILE NAME ERROR (536): format not supported
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Append code from selected file to internal FPA buffer to be used in programming. Only code data that fits within the target MCUs memory space will be read, and the rest will be discarded.
Already read code data is not overwritten by newly appended file. Existing code data locations that contain the default empty value (for most MCUs it is 0xFF, for some it is 0x00) can be overwritten if the OverwriteEmptyValues option is enabled in the Preferences file, prefer.ini (read from current working directory). By default, no overwrites are performed.
Syntax
INT_X F_AppendCodeFile( char * FileName )
Input
char * FileName : path to code file including filename and extension
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
TRUE (1) : succeeded
STATUS OPEN FILE ERROR (535): could not open file
STATUS MAX FILE COUNT (557): total number of files exceeds MAX FILE INDEX (20)
STATUS DUPLICATE FILE PATH (558): appending already existing file
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Read code from selected buffer and calculate check sum.
Syntax
INT_X F_Get_CodeCS( INT_X dest )
Input
INT X dest : choose operation
1 : Calculate checksum of code from internal Code Buffer
2 : Calculate checksum of code used in last F AutoProgram or F Memory Write operation.
3 : Calculate checksum of flash memory read after last F AutoProgram or F Memory Verify operation.
•
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
any : checksum
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus(avoid this by not using FPA index 0)
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range(avoid this by using F Check FPA index first)
•
...
General Description
Clear contents of internal code buffer.
Syntax
INT_X F_Clr_Code_Buffer( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Write to internal code buffer. Can be used instead of or in conjunction with the F ReadCodeFile function. When starting from scratch, use the F Clr Code Buffer function to clear the internal code buffer.
Syntax
INT_X F_Put_Byte_to_Code_Buffer( INT_X addr, BYTE data )
Input
INT X addr : valid flash address for target MCU
BYTE data : new byte to be written to internal code buffer
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Read from internal code buffer. Can be used in conjunction with F Put Byte to Code Buffer to verify writes to internal code buffer.
Syntax
INT_XF_Get_Byte_from_Code_Buffer( INT_X addr )
Input
INT X addr : valid flash address for target MCU
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
BYTE (0 to 0xFF) : byte from internal code buffer
-1 : addr parameter out of flash range
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Write byte to temporary Write Data Buffer (see Figure 1.2).
Syntax
INT_X F_Put_Byte_to_Buffer( INT_X addr, BYTE data )
Input
INT X addr : valid flash address for target MCU
BYTE data : new byte to be written to temporary Write Data Buffer
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
...
General Description
Read from temporary Read Data Buffer (see Figure 1.2).
Syntax
INT_X F_Get_Byte_from_Buffer( INT_X addr )
Input
INT X addr : valid flash address for target MCU
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
BYTE (0 to 0xFF) : byte from temporary Write Data Buffer
-1 : addr parameter out of flash range
FPA UNMATCHED RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to F LastStatus
•
FPA INVALID NO (-2 or 0xFFFFFFFE) : FPA not opened with F OpenInstancesAndFPAs or index out of range
•
| Anchor | |||
|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Perform full programming sequence on selected FPA. Power on (optional), open communication, erase, blank check, program, verify and lock device (optional). Exact behavior of each action is controlled through configuration settings (i.e. PowerFromFpaEn has to be enabled to power target device from FPA, otherwise outside power source is required).
Syntax
INT_X F_AutoProgram( INT_X mode )
Input
INT X mode : for future use (currently has no effect)
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Determine if FPA has successfully established communication with the target device. This step requires a working connection, a read of the processor ID, memory size, and flash size checked against internal records (except when target MCU doesn’t have this meta-data available), and calibration of internal CPU clock. If these steps match expected values the operation will succeed. This function is internally called by all other encapsulated functions at startup before they proceed to perform any other operations (except one). Therefore if this function fails, other encap- sulated functions will invariably fail as well. The exception is F Clear Locked Device which uses a
custom procedure to unlock the MCU (if supported by vendor).
Syntax
INT_X F_Verify_Access_to_MCU( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Erase memory specified in configuration options. Depending on settings, this operation will erase all or part of target device’s memory contents. Use Retain Data settings to preserve calibration or custom data. Retain Data settings only apply to encapsulated functions (F AutoProgram, this function, etc.) custom writes using Data Buffer or Sequential instructions will not retain data.
Syntax
INT_X F_Memory_Erase( INT_X mode )
Input
INT X mode : type of memory erase operation
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
Blank check memory specified in configuration options. Depending on settings, this operation will blank check all or part of target device’s memory contents.
Syntax
INT_X F_Memory_Blank_Check( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Write contents of Code Buffer to target device’s memory. The Code Buffer is usually written from a code file using F ReadCodeFile, but can be modified with custom instructions such as F Put Byte to Code Buffer. An enabled configuration option, CodeFileReload, will cause this function to always reload code file before proceeding. This setting can be useful if code file is frequently modified, but it can cause issues if custom instructions are used to modify the code buffer before programming, as their modifications will be discarded.
Syntax
INT_X F_Memory_Write( INT_X mode )
Input
INT X mode : for future use (currently has no effect)
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Verify target device’s memory contents against Code Buffer. The sections compared depend on configuration settings, and are identical to sections of memory being programmed using F Memory Write. For common behavior, do not modify settings between calling F Memory Write and this function.
Syntax
INT_X F_Memory_Verify( INT_X mode )
Input
INT X mode : for future use (currently has no effect)
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
Read target device’s memory contents and store in Read Data Buffer (see Figure 1.2). The sections of memory read depend on configuration settings, FlashReadModeIndex. Use F Get Byte from Buffer to access the contents of this buffer after this function has completed.
Syntax
INT_X F_Memory_Read( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
This procedure is not supported by all target devices. Consult individual device manuals or the FlashPro GUI, Setup, Memory Protection window which will indicate which bits can be set.
Syntax
INT_X F_Lock_MCU( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Will attempt to return all memory to factory settings. Usually requires a mass erase of the memory contents. This procedure can be used to unlock memory protection or enable debug access after the F Lock MCU procedure.
This procedure is not supported by all target devices. Consult individual device manuals or the FlashPro GUI, Setup, Memory Protection window which will indicate which bits can be reset.
Syntax
INT_X F_Clear_Locked_Device( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
The FPA will establish communication with the target device. This step requires a working con- nection, a read of the processor ID, memory size, and flash size checked against internal records (except when target MCU doesn’t have this meta-data available), and calibration of internal CPU clock. If these steps match expected values the operation will succeed.
This function is identical to F Verify Access to MCU except that the target device is not closed when this function concludes (F Open Target Device keeps the target device open to accept further instructions listed below).
Syntax
INT_X F_Open_Target_Device( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Terminates communication between FPA and target device. Sets reset line to GND and communi- cation lines (TMS, TCK, TDI) to configuration setting ReleaseJtagState.
Syntax
INT_X F_Close_Target_Device( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Send command to erase target device’s memory segment.
Syntax
INT_X F_Segment_Erase( INT_X address );
Input
INT X address : address of segment/sector to be erased
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Blank check part or all of the target device’s memory.
Syntax
INT_X F_Sectors_Blank_Check( INT_X start_addr, INT_X stop_addr );
Input
INT X start addr : first memory address to be included in blank check (inclusive) INT X stop addr : last memory address to be included in blank check (inclusive)
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Write specified number of bytes from temporary Write Data Buffer (see Figure 1.2) to MCU flash or OTP.
Syntax
INT_X F_Copy_Buffer_to_Flash( INT_X start_addr, INT_X size )
Input
INT X start addr : valid flash or OTP start address
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Read specified number of bytes from MCU flash or OTP to temporary Read Data Buffer (see Figure 1.2).
Syntax
INT_X F_Copy_Flash_to_Buffer( INT_X start_addr, INT_X size )
Input
INT X start addr : valid flash or OTP start address
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to write a byte to the target device’s RAM. This write is not verified (no read performed). Use F Read Byte to verify.
Syntax
INT_X F_Write_Byte_to_RAM( INT_X addr, BYTE data )
Input
INT X addr : address of byte to be written (byte addressable) BYTE data : byte to be written
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to write two bytes to the target device’s RAM. This write is not verified (no read performed). Use F Read Word16 to verify.
Syntax
INT_X F_Write_Word16_to_RAM( INT_X addr, INT_X data )
Input
INT X addr : address of 16-bit data to be written (byte addressable) INT X data : 16-bit data to be written
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to write four bytes to the target device’s RAM. This write is not verified (no read performed). Use F Read Word32 to verify.
Syntax
INT_X F_Write_Word32_to_RAM( INT_X addr, INT_X data )
Input
INT X addr : address of 32-bit data to be written (byte addressable) INT X data : 32-bit data to be written
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to write a block of bytes to RAM. Currently this function only writes a block of bytes with a size that is a multiple of four, to a 32-bit word aligned address. These writes are not verified (no reads performed). Use F Read Bytes Block to verify.
Syntax
INT_X F_Write_Bytes_Block_to_RAM( INT_X addr, INT_X size, BYTE *data )
Input
INT X addr : address of 32-bit data to be written (byte addressable) INT X size : number of bytes to be written
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to read one byte from any address (RAM, flash, etc.).
Syntax
INT_X F_Read_Byte( INT_X addr )
Input
INT X addr : address of byte to be read
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : data read
0-0xFF : byte value
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to read two bytes from any address (RAM, flash, etc.).
Syntax
INT_X F_Read_Word16( INT_X addr )
Input
INT X addr : address of 16-bit word to be read
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : data read
0-0xFFFF : 16-bit word value
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to read four bytes from any address (RAM, flash, etc.).
Syntax
INT_X F_Read_Word32( INT_X addr )
Input
INT X addr : address of 32-bit word to be read
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : data read
0-0xFFFFFFFF : 32-bit word value
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Use the FPA to read a block of bytes from any address (RAM, flash, etc.).
Syntax
INT_X F_Read_Bytes_Block( INT_X addr, INT_X size, BYTE *data );
Input
INT X addr : first byte address to be read (byte addressable) INT X size : number of bytes to be read
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Start target MCU from specified program counter (PC). There should be a valid instruction at the target address.
Syntax
INT_X F_Set_PC_and_RUN( INT_X PC_addr )
Input
INT X PC addr : set program counter to this address and start processor
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Write to non-volatile memory protection bits and/or persistent user-data registers (if supported). Does not block communication over debug interface, but can disable writing and/or reading from target device’s memory. These bits can be reset to factory settings using the F Clear Locked Device function if the device supports it. To write protection bits, enable the WriteLockingBitsEn config- uration option.
Syntax
INT_X F_Write_Locking_Registers( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Write to non-volatile protection bits to disable communication over debug interface. These bits can be reset to factory settings using the F Clear Locked Device function if the device supports it. To disable debug access, enable WriteLockingBitsEn and (vendor) USER DBG WrEn configuration options.
Syntax
INT_X F_Write_Debug_Register( void )
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Return the MCU ID, flash size, or RAM size read by the FPA to identify a specific target device, if supported by vendor.
Syntax
INT_X F_Get_MCU_Data( INT_X type )
Input
INT X type : select type of information to receive
...
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Read program counter (PC) register using debug interface.
Syntax
INT_X F_Capture_PC_Addr( void );
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
General Description
Stop target device (debug enable and halt).
Syntax
INT_X F_Synch_CPU_JTAG();
Input
none.
Select FPA to perform operation on using F Set FPA index, index 1 to 64.Use index 0 to perform operation on all FPAs (if results differ, use F LastStatus to get individual results).
Output
INT X : result of operation
...