1. F OpenInstancesAndFPAs
1.1. 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.
1.2. 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.
1.3. Syntax
INT_X F_OpenInstancesAndFPAs( char * FileName )
1.4. 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 |
1.5. Output
INT X : number of instances opened successfully
2. F CloseInstances
2.1. 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.
2.2. Syntax
INT_X F_CloseInstances ( void );
2.3. Input
none.
2.4. Output
INT X : success
TRUE (1)
3. F Set FPA index
3.1. General Description
Select desired FPA index to perform specific tasks (access specific API-DLL instance).
3.2. Syntax
INT_X F_Set_FPA_index ( BYTE fpa );
3.3. Input
BYTE fpa : desired FPA index, 1 to 64, or 0 for all
3.4. 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
•
3.5. IMPORTANT
Other functions that try to access FPAs will also return FPA INVALID NO if this function was not called with a proper parameter.
4. F Get FPA index
4.1. General Description
Get current FPA index.
4.2. Syntax
BYTE F_Get_FPA_index( void );
4.3. Input
none.
4.4. Output
BYTE : current FPA index as entered using F Set FPA index
5. F Check FPA index
5.1. 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.
5.2. Syntax
INT_X F_Check_FPA_index ( void );
5.3. Input
none.
5.4. 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
•
6. F Enable FPA index
6.1. 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).
6.2. Syntax
void F_Enable_FPA_index ( BYTE fpa );
6.3. Input
BYTE fpa : desired FPA index, 1 to 64
6.4. Output
none.
7. F Disable FPA index
7.1. 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).
7.2. Syntax
void F_Disable_FPA_index ( BYTE fpa );
7.3. Input
BYTE fpa : desired FPA index, 1 to 64
7.4. Output
none.
8. F LastStatus
8.1. 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.
8.2. Syntax
INT_X F_LastStatus ( BYTE fpa );
8.3. Input
BYTE fpa : desired FPA index, 1 to 64.
8.4. 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
•
9. F Multi DLLTypeVer
9.1. General Description
Get Multi API-DLL software version number.
9.2. Syntax
INT_X F_Multi_DLLTypeVer( void );
9.3. Input
none.
9.4. 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
•
10. F Get FPA SN
10.1. General Description
Get serial number (SN) of FPA assigned to specified index.
10.2. Syntax
INT_X F_Get_FPA_SN ( BYTE fpa );
10.3. Input
BYTE fpa : desired FPA index, 1 to 64
10.4. 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
•
11. F Get FPA Label
11.1. General Description
Get detailed information of FPA assigned to specified index.
11.2. Syntax
INT_X F_Get_FPA_Label ( BYTE fpa, BYTE *label );
11.3. Input
BYTE fpa : desired FPA index, 1 to 64.
BYTE *label : pointer to byte array, of at least FPA LABEL SIZE (80 bytes)
11.4. 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;
};
12. F GetProgressBar
12.1. 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).
12.2. Syntax
INT_X MSPPRG_API F_GetProgressBar( BYTE fpa );
12.3. Input
BYTE fpa : desired FPA index, 1 to 64.
12.4. 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
•
12.5. Example
Refer to GetLastOpCode.
13. F GetLastOpCode
13.1. 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).
13.2. Syntax
INT_X MSPPRG_API F_GetLastOpCode( BYTE fpa );
13.3. Input
BYTE fpa : desired FPA index, 1 to 64.
13.4. 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
•
13.5. 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);
}
14. Trace ON
14.1. 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.
14.2. Syntax
void F_Trace_ON( void );
14.3. Input
none.
14.4. Output
none.
Trace OFF General Description Disable tracing.
14.5. Syntax
void F_Trace_OFF( void );
14.6. Input
none.
14.7. Output
none.