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.).
Blank check is enabled by default but can be disabled to save time by disabling configuration option General Configuration | EnableBlankCheck .
The target device can be locked at the end of this procedure if Memory Protection Configuration | WriteLockingBitsEn is enabled. Even if enabled, custom MCU protection bits need to be configured (check Memory Protection section in this Guide for your vendor)
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 6FPA_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
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.
If General Configuration | MetadataWrnIsErr is disabled, only the processor ID needs to match records, the RAM and flash size do not. If the RAM and flash do not match a warning will be printed and accessible via Generic Functions | F_ReportMessage
If General Configuration | MetadataWrnIsErr is enabled, all values need to match, processor ID, RAM size, and flash size, otherwise function will fail.
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 6FPA_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
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 Data Buffer Functions or Sequential Functions 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 6FPA_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
4. F_Memory_Blank_Check
Blank check memory specified in configuration options. Depending on settings, this operation will blank check all or part of target device’s memory contents. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Memory_Blank_Check( 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 6FPA_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
5. F_Memory_Write
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 Data Buffer Functions. An enabled configuration option, https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57802857/General+Configuration#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. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Memory_Write( 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 6FPA_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
6. F_Memory_Verify
General Description
Verify target device’s memory contents against Code Buffer. The memory used for verification depends on configuration settings, and is identical to sections of memory being programmed using https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57770414/Encapsulated+Functions#F_Memory_Write. For common behavior, do not modify settings between calling https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57770414/Encapsulated+Functions#F_Memory_Write and this function. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Memory_Verify( 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 6FPA_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
7. F_Memory_Read
Read target device’s memory contents.
FlashPro-ARM - store in Read Data Buffer shown in https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#FlashPro-ARM-buffers
GangPro-ARM - store in Gang Read Buffers shown inhttps://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#GangPro-ARM-buffers
The sections of memory read depend on configuration settings. Use Data Buffer Functions to access the contents of this buffer after this function has completed. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Memory_Read( 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 6FPA_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
8. F_Lock_MCU
This function can write memory protection bits and disable debug access. Performs the functions Sequential Functions F_Write_Locking_Registers and F_Write_Debug_Register together. If the former fails, the latter will not execute (locking bits are verified first before debug access is disabled). If https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57770239/Memory+Protection+Overview#WriteLockingBitsEn is not enabled this function will not perform any action.
This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Lock_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 6FPA_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
9. F_Clear_Locked_Device
General Description
Will attempt to return MCU 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 https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57770414/Encapsulated+Functions#F_Lock_MCU function.
This procedure is not supported by all target devices, or a target device might be permanently locked with settings that are not reversible. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Clear_Locked_Device( 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 6FPA_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