Page Comparison

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 to initialize the FPAs, and configure them for the target device(s) being programmed.

12

F OpenInstancesAndFPAs

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:

and with FPA-3 missing (not connected, etc.) will initialize the Multi API-DLL to:

Output

INT X : number of instances opened successfully

F_CloseInstances_bookmark191_bookmark191F CloseInstances

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)

F_Set_FPA_index_bookmark192_bookmark192F Set FPA index

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.

F_Get_FPA_index_bookmark193_bookmark193F Get FPA index

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

F_Check_FPA_index_bookmark194_bookmark194F Check 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

•

F_Enable_FPA_index_bookmark195_bookmark195F Enable FPA index

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.

F_Disable_FPA_index_bookmark196_bookmark196F Disable FPA index

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.

F_LastStatus_bookmark197_bookmark197F LastStatus

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

•

F_Multi_DLLTypeVer_bookmark198_bookmark198F Multi DLLTypeVer

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

•

F_Get_FPA_SN_bookmark199_bookmark199F Get FPA SN

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

•

F_Get_FPA_Label_bookmark200_bookmark200F Get FPA Label

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;

};

F_GetProgressBar_bookmark201_bookmark201F GetProgressBar

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.

F_GetLastOpCode_bookmark202_bookmark202F 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);

}

Trace_ON_bookmark203_bookmark203Trace ON

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.

Trace_OFF_bookmark204_bookmark204Trace OFF General Description Disable tracing.

Syntax

void F_Trace_OFF( void );

Input

none.

Output

none.