Multi API-DLL Functions

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:

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

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.