/
Encapsulated Functions

Encapsulated Functions

Encapsulated functions are powerful and easy to use. When called, these functions perform all device actions from beginning to end automatically.

These functions require that all FPAs are opened using the Multi API-DLL function F_OpenInstancesAndFPAs and each API-DLL instance is correctly initialized using Generic Functions. If not already included in configuration settings, the code being programmed by each FPA to its target device can be set using Data Buffer Functions.

Encapsulated functions use the following sequence:

  • FPA opens target device according to configuration settings (power source, reset, etc.),

  • FPA establishes communication with target device (JTAG/SWD), checks ID, calibrates clock,

  • FPA performs selected encapsulated function,

  • FPA terminates communication with target device,

FPA closes target device according to configuration settings (power setting, Application Start for F_AutoProgram only, adapter line states, etc.)

 

1. F_AutoProgram

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, etc.).

This function has some exclusive GangPro-ARM return values.

Syntax

INT_X F_AutoProgram( INT_X mode = 0 );

Input

INT_X mode : for future use (currently has no effect)


Select FPA to perform operation on using Multi API-DLL Functions | F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use Multi API-DLL Functions | F_LastStatus to get individual results).

Output

INT_X : result of operation

  • FALSE (0) : failed

  • FlashPro-ARM - TRUE (1) : succeeded

  • GangPro-ARM - TRUE MASK (0x01..0x3F) : 0x01 - target 1, 0x02 - target 2, 0x04 - target 3, 0x08 - target
    4, 0x10 - target 5, 0x20 - target 6

  • FPA_UNMATCHED_RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to Multi API-DLL Functions | F_LastStatus

  • FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

2. F_Verify_Access_to_MCU

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, RAM 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. Therefore if this function fails, other encapsulated functions will invariably fail as well. The exception is Encapsulated Functions | F_Clear_Locked_Device which uses a custom procedure to unlock the MCU (if supported by vendor). This function has some exclusive GangPro-ARM return values.

Syntax

INT_X F_Verify_Access_to_MCU( void );

Input

none.


Select FPA to perform operation on using Multi API-DLL Functions | F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use Multi API-DLL Functions | F_LastStatus to get individual results).

Output

INT_X : result of operation

  • FALSE (0) : failed

  • FlashPro-ARM - TRUE (1) : succeeded

  • GangPro-ARM - TRUE MASK (0x01..0x3F) : 0x01 - target 1, 0x02 - target 2, 0x04 - target 3, 0x08 - target
    4, 0x10 - target 5, 0x20 - target 6

  • FPA_UNMATCHED_RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to Multi API-DLL Functions | F_LastStatus

  • FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range

3. F_Memory_Erase

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 https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57770414/Encapsulated+Functions#F_AutoProgram and this function. Custom writes using https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798 or https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704843 will not retain data. This function has some exclusive GangPro-ARM return values.

Syntax

INT_X F_Memory_Erase( INT_X mode = 0 );

Input

INT_X mode : type of memory erase operation

  • 0 : erase memory specified by configuration option “FlashEraseModeIndex”

  • 1 : erase all flash memory, regardless of configuration options


Select FPA to perform operation on using Multi API-DLL Functions | F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use Multi API-DLL Functions | F_LastStatus to get individual results).

Output

INT_X : result of operation

  • FALSE (0) : failed

  • FlashPro-ARM - TRUE (1) : succeeded

  • GangPro-ARM - TRUE MASK (0x01..0x3F) : 0x01 - target 1, 0x02 - target 2, 0x04 - target 3, 0x08 - target
    4, 0x10 - target 5, 0x20 - target 6

  • FPA_UNMATCHED_RESULTS (-1 or 0xFFFFFFFF) : Result of operation inconsistent across all selected FPAs, refer to Multi API-DLL Functions | F_LastStatus

  • FPA_INVALID_NO (-2 or 0xFFFFFFFE) : FPA not opened with Multi API-DLL Functions | F_OpenInstancesAndFPAs or index out of range