Having setup the Multi API-DLL and API-DLL instances for the correct target devices using functions from previous sections. Use the functions in this section to specify what code should be written by each FPA to their target device.
All data coming to and from the target device is saved in temporary buffers located inside each API-DLL instance. In summary, these buffers are the Code Data Buffer, Write Data Buffer, and Read Data Buffer shown below:
During normal programming using Encapsulated Functions, such as F_AutoProgram, the Code Data Buffer is used to program the target device.
Custom Writes:
For custom modifications the Write Buffer can be used to write to the target device(s) without disturbing the Code Data Buffer. To modify the Write Buffer, use the function F_Put_Byte_to_Buffer. When using FlashPro-ARM, the one target will be modified, when using GangPro-ARM, all six targets will be written with the same data. Sequential Functions, such as F_Copy_Buffer_to_Flash can be used to write this buffer to target(s).
Additionally the GangPro-ARM library also has six Gang Write Buffers, where different custom data can be written to each of the six targets per adapter using the function F_Put_Byte_to_Gang_Buffer. Each target can be provided different data for the same address, i.e. calibration or serialization data. Use Sequential Functions, such as F_Copy_Gang_Buffer_to_Flash to write these buffers to targets.
Custom Reads:
FlashPro-ARM: The Read Data Buffer is used for reading from the target device by the F_Copy_Flash_to_Buffer and F_Memory_Read functions, the contents of which can be accessed using F_Get_Byte_from_Buffer.
GangPro-ARM: Six Gang Read Buffers are used for reading from up to six target devices by the F_Copy_Flash_to_Gang_Buffer and F_Memory_Read functions, the contents of which can be accessed using F_Get_Byte_from_Gang_Buffer.
1. F_ReadCodeFile
General Description
Read code from file and store in internal FPA buffer to be used in programming. Only code data that fits within the target MCUs memory space will be read, and the rest will be discarded. Therefore, it is necessary to configure the FPA for the correct MCU first, then load the code file. Unspecified locations within the code file are set to the target MCU’s default empty value (for most MCUs it is 0xFF, for some it is 0x00).
Syntax
INT_X F_ReadCodeFile( char * FileName )
Input
char * FileName : path to code file including filename and extension
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT_X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS_OPEN_FILE_ERROR (535): could not open file
STATUS_FILE_NAME_ERROR (536): format not supported
FPA_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_ReadCodeFile_BaseAddr
General Description
Same as https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#F_ReadCodeFIle but designed for *.bin files. Function will add baseAddr to code address. Can also be used to shift regular code files by a fixed amount.
Syntax
INT_X F_ReadCodeFile_BaseAddr( char * FileName, UINT32 baseAddr );
Input
char * FileName : path to code file including filename and extension
UINT32 baseAddr : unsigned 32-bit offset added to all data addresses from code file
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT_X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS_OPEN_FILE_ERROR (535): could not open file
STATUS_FILE_NAME_ERROR (536): format not supported
FPA_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_AppendCodeFile
General Description
Append code from selected file to internal FPA buffer to be used in programming. Only code data that fits within the target MCUs memory space will be read, and the rest will be discarded.
If overlapping code data is detected the function will return FALSE, unless existing code data locations contain the default empty value (for most MCUs it is 0xFF, for some it is 0x00) and the “OverwriteEmptyValues”, https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57802857/General+Configuration#OverwriteEmptyValues, option is enabled in the configuration. By default, no overwrites are allowed.
Syntax
INT_X F_AppendCodeFile( char * FileName )
Input
char * FileName : path to code file including filename and extension
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT_X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS_OPEN_FILE_ERROR (535): could not open file
STATUS_FILE_NAME_ERROR (536): format not supported
STATUS_MAX FILE_COUNT (557): total number of files exceeds MAX_FILE_INDEX (20)
STATUS_DUPLICATE_FILE PATH (558): appending already existing file
FPA_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_AppendCodeFile_BaseAddr
General Description
Same as https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#F_AppendCodeFIle but designed for *.bin files. Function will add baseAddr to code address. Can also be used to shift regular code files by a fixed amount.
Syntax
INT_X F_AppendCodeFile_BaseAddr( char * FileName, UINT32 baseAddr );
Input
char * FileName : path to code file including filename and extension
UINT32 baseAddr : unsigned 32-bit offset added to all data addresses from code file
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT_X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
STATUS_OPEN_FILE_ERROR (535): could not open file
STATUS_FILE_NAME_ERROR (536): format not supported
STATUS_MAX FILE_COUNT (557): total number of files exceeds MAX_FILE_INDEX (20)
STATUS_DUPLICATE_FILE PATH (558): appending already existing file
FPA_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_Get_CodeCS
General Description
Read code from selected buffer and calculate check sum. This function has some exclusive GangPro-ARM return values.
Syntax
INT_X F_Get_CodeCS( INT_X dest )
Input
INT X dest : choose operation
1 : Checksum of code from internal Code Buffer
2 : Checksum of code used in last F_AutoProgram or F_Memory_Write operation.
3 : Checksum of target 1 memory read after last F_AutoProgram or F_Memory_Verify operation.
0x10 : Checksum of last used code (same as 2)
0x11: Checksum of target 1 memory (same as 3)
0x12: Checksum of target 2 memory (GangPro-ARM only)
0x13: Checksum of target 3 memory (GangPro-ARM only)
0x14: Checksum of target 4 memory (GangPro-ARM only)
0x15: Checksum of target 5 memory (GangPro-ARM only)
0x16: Checksum of target 6 memory (GangPro-ARM only)
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
any : checksum
FPA_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_Clr_Code_Buffer
General Description
Clear contents of internal code buffer.
Syntax
INT_X F_Clr_Code_Buffer( void )
Input
none.
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA_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_Put_Byte_to_Code_Buffer
General Description
Write to internal code buffer. Can be used instead of or in conjunction with the https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#F_ReadCodeFIle function to modify an existing code buffer before running F_AutoProgram. When starting from scratch, use the F_Clr_Code_Buffer function to clear the internal code buffer.
Syntax
INT_X F_Put_Byte_to_Code_Buffer( INT_X addr, BYTE data );
Input
INT X addr : valid flash address for target MCU
BYTE data : new byte to be written to internal code buffer
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA_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_Get_Byte_from_Code_Buffer
General Description
Read from internal code buffer. Can be used in conjunction with https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#F_Put_Byte_to_Code_Buffer to verify writes to internal code buffer.
Syntax
INT_X F_Get_Byte_from_Code_Buffer( INT_X addr );
Input
INT X addr : valid flash address for target MCU
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
BYTE (0 to 0xFF) : byte from internal code buffer
-1 : addr parameter out of flash range
FPA_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_Put_Byte_to_Buffer
General Description
Write byte to Write Buffer from FlashPro-ARM buffer https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#FlashPro-ARM-buffers and GangPro-ARM buffer https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#GangPro-ARM-buffers
Syntax
INT_X F_Put_Byte_to_Buffer( INT_X addr, BYTE data );
Input
INT X addr : valid flash address for target MCU
BYTE data : new byte to be written to temporary Write Buffer
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA_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
Example
The condition for this example to work properly is that F_OpenInstancesAndFPAs, and F_Initialization has correctly initialized the given fpa index (1 to 64). If testing adapter 1, the user should call F_Set_FPA_index(1) before this code executes. In addition the user should load the intended configuration file using F_ConfigFileLoad so that the right MCU is selected.
MCU_Info struct was initialized using example Get MCU Info.
The code sequence is as follows:
Power on target device and open communication using
F_Open_Target_DeviceGet MCU base flash address,
MCU_Info.u.x.FlashStartAddr, and add 0x100. This code will write custom bytes to almost the start of flash.In a loop, populate the Write Buffer with custom bytes starting at address
addrusingF_Put_Byte_to_BufferProgram custom bytes to target using
F_Copy_Buffer_to_FlashRead target memory and save contents to Read Data Buffer using
F_Copy_Flash_to_BufferIn a loop, read bytes from the Read Data Buffer and print them using
F_Get_Byte_from_BufferPower down target and close communication using
F_Close_Target_Device
INT_X response;
const int size=32;
response = F_Open_Target_Device();
if(response != TRUE)
return response;
char text[200];
long addr = MCU_Info.u.x.FlashStartAddr + 0x100;
for(int k=0; k< size; k++)
{
//----------------------------------------------------
F_Put_Byte_to_Buffer( (INT_X )(addr+k), (BYTE)( 0x10 + k ));
//----------------------------------------------------
}
//----------------------------------------------------
response = F_Copy_Buffer_to_Flash( addr, size );
if(response != TRUE)
return response;
//----------------------------------------------------
//----------------------------------------------------
response = F_Copy_Flash_to_Buffer( addr, size );
if(response != TRUE)
return response;
//----------------------------------------------------
for( int n=0; n<size; n += 16 )
{
for( int k = 0; k<16; k++ )
{
//----------------------------------------------------
sprintf( text+3*k, "%2.2X ", F_Get_Byte_from_Buffer((INT_X )( addr + k + n) ));//for single buffer, when reading it works only for FlashPro
//----------------------------------------------------
}
strcat( text, "\r\n" );
printf("%s", text);
}
response = F_Close_Target_Device();
if(response != TRUE)
return response;
10. F_Get_Byte_from_Buffer (FlashPro-ARM only)
General Description
Read from Read Data Buffer from FlashPro-ARM bufferhttps://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#FlashPro-ARM-buffers
Syntax
INT_X F_Get_Byte_from_Buffer( INT_X addr );
Input
INT X addr : valid flash address for target MCU
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
BYTE (0 to 0xFF) : byte from temporary Write Data Buffer
-1 : addr parameter out of flash range
FPA_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
11. F_Put_Byte_to_Gang_Buffer (GangPro-ARM only)
General Description
Write byte to Gang Write Buffer from GangPro-ARM buffer https://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#GangPro-ARM-buffers. This function will set one byte of data in a dedicated buffer for specified Gang target MCU (1 to 6). Use in combination with F_Copy_Gang_Buffer_to_Flash to actually write data to targets.
Syntax
INT_X MSPPRG_API F_Put_Byte_to_Gang_Buffer( BYTE target_no, INT_X addr, BYTE data );
Input
BYTE target_no : MCU target number 1 to 6
INT_X addr : valid flash address for target MCU
BYTE data : new byte to be written to temporary Write Buffer
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
FALSE (0) : failed
TRUE (1) : succeeded
FPA_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
Example
The condition for this example to work properly is that F_OpenInstancesAndFPAs, and F_Initialization has correctly initialized the given fpa index (1 to 64). If testing adapter 1, the user should call F_Set_FPA_index(1) before this code executes. In addition the user should load the intended configuration file using F_ConfigFileLoad so that the right MCU is selected.
MCU_Info struct was initialized using example Get MCU Info.
The code sequence is as follows:
Power on target devices and open communication using
F_Open_Target_DeviceThe return value is a TRUE MASK (0x01..0x3F) : 0x01 - target 1, 0x02 - target 2, 0x04 - target 3, 0x08 - target
4, 0x10 - target 5, 0x20 - target 6, if at least one target succeeded then proceed further.Get MCU base flash address,
MCU_Info.u.x.FlashStartAddr, and add 0x100. This code will write custom bytes to almost the start of flash.In a loop, populate the Gang Write Buffer for target 1 with custom bytes starting at address
addrusingF_Put_Byte_to_Gang_Buffer. The user can change the first parameter to write different bytes to target 2, 3, 4, 5, or 6.Program custom bytes to targets using
F_Copy_Gang_Buffer_to_FlashRead target memories and save contents to Gang Read Buffers (6) using
F_Copy_Flash_to_Gang_BufferIn a loop, read bytes from the Gang Read Buffers and print them using
F_Get_Byte_from_Gang_Buffer, this example iterates over 6 target buffers.Power down targets and close communication using
F_Close_Target_Device
#define ANY_TARGET 0x3F
INT_X response;
const int size=32;
response = F_Open_Target_Device();
if((response & ANY_TARGET) == 0)
return response;
char text[1000];
long addr = MCU_Info.u.x.FlashStartAddr + 0x100;
for(int k=0; k< size; k++)
{
//----------------------------------------------------
F_Put_Byte_to_Gang_Buffer( 1, (INT_X )(addr+k), (BYTE)( 0x10 + k ));
//----------------------------------------------------
}
//----------------------------------------------------
response = F_Copy_Gang_Buffer_to_Flash( addr, size );
if((response & ANY_TARGET) == 0)
return response;
//----------------------------------------------------
//----------------------------------------------------
response = F_Copy_Flash_to_Gang_Buffer( addr, size );
if((response & ANY_TARGET) == 0)
return response;
//----------------------------------------------------
if( F_Get_Active_Targets_Mask() == response )
{
sprintf( text, "Read from FLASH - address 0x%4.4X\r\n", addr );
printf("%s", text);
for(int p=0; p<GANG_SIZE; p++)
{
for( int n=0; n<size; n += 16 )
{
for( int k = 0; k<16; k++ )
{
//----------------------------------------------------
sprintf( text+3*k, "%2.2X ", F_Get_Byte_from_Gang_Buffer( (p+1), (INT_X )( addr + k + n) ));//for gang buffer, when reading in GangPro
//----------------------------------------------------
}
strcat( text, "\r\n" );
printf("%s", text);
}
}
}
response = F_Close_Target_Device();
if((response & ANY_TARGET) == 0)
return response;
12. F_Get_Byte_from_Gang_Buffer (GangPro-ARM only)
General Description
Read byte from Gang Read Buffer from GangPro-ARM bufferhttps://elprotronic.atlassian.net/wiki/spaces/FPGPARM/pages/57704798/Data+Buffer+Functions#GangPro-ARM-buffers. This function will read one byte of data from a dedicated buffer for specified Gang target MCU (1 to 6). Use in combination with F_Copy_Flash_to_Gang_Buffer.
Syntax
INT_X MSPPRG_API F_Get_Byte_from_Gang_Buffer( BYTE target_no, INT_X addr );
Input
BYTE target_no : MCU target number 1 to 6
INT X addr : valid flash address for target MCU
Select FPA to perform operation on using F_Set_FPA_index, index 1 to 64. Use index 0 to perform operation on all FPAs (if results differ, use F_LastStatus to get individual results).
Output
INT X : result of operation
BYTE (0 to 0xFF) : byte from Gang Read Buffer of one target (target_no)
-1 : addr parameter out of flash range
FPA_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