Data Buffer Functions

Owned by Adam Czajkowski
Last updated: Dec 12, 2023
10 min read

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:

FlashPro-ARM: Illustration of how the Multi API-DLL controls the API-DLL instances for FlashPro-ARM. Calls to the Multi API-DLL are forwarded based on the FPA index.

GangPro-ARM: Illustration of how the Multi API-DLL controls the API-DLL instances for the GangPro-ARM. Calls to the Multi API-DLL are forwarded based on the FPA index. Each FPA can program up to 6 targets with a shared Code Data Buffer, or with six(6) distinct Gang Write Buffers to write different data per target. The GangPro-ARM API-DLL also contains six(6) distinct Gang Read Buffers to read each target individually.

 

 

 

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

2. F_ReadCodeFile_BaseAddr

General Description

Same as 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 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

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”, 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 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

  • 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 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

4. F_AppendCodeFile_BaseAddr

General Description

Same as 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

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

  • 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 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

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

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

 

6. F_Clr_Code_Buffer

General Description

Clear contents of internal code buffer.

Syntax

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

7. F_Put_Byte_to_Code_Buffer

General Description

Write to internal code buffer. Can be used instead of or in conjunction with the 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

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

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

Input

INT_X addr : valid flash address for target MCU

 

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

9. F_Put_Byte_to_Buffer

General Description

Write byte to Write Buffer from FlashPro-ARM buffer Data Buffer Functions | FlashPro-ARM-buffers and GangPro-ARM buffer Data Buffer Functions | GangPro-ARM-buffers.

Syntax

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

  • TRUE (1) : succeeded

  • STATUS_TXBUF_SIZE_ERROR (559): Temporary buffer full (4k), program contents with F_Copy_Buffer_to_Flash. This buffer is flushed when F_Open_Target_Device is called, or when addr is set to -1. Call F_Put_Byte_to_Buffer(-1, 0xFF); to flush buffer.

  • 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

Example

Custom Buffer Write and Verify - FlashPro-ARM

10. F_Get_Byte_from_Buffer (FlashPro-ARM only)

General Description

Read from Read Data Buffer from FlashPro-ARM bufferData Buffer Functions | FlashPro ARM buffers

Syntax

Input

INT_X addr : valid flash address for target MCU

 

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

11. F_Put_Byte_to_Gang_Buffer (GangPro-ARM only)

General Description

Write byte to Gang Write Buffer from GangPro-ARM buffer 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

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

Example

Custom Buffer Write and Verify - GangPro-ARM

12. F_Get_Byte_from_Gang_Buffer (GangPro-ARM only)

General Description

Read byte from Gang Read Buffer from GangPro-ARM bufferData 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

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

Example

Refer to Data Buffer Functions | F_Put_Byte_to_Gang_Buffer