GtDio6xFileImport

Applies To

General utility function.

Purpose

Converts WGL/STIL/VCD/eVCD and ATP file types to a GtDio6x file. Note: this function requires GTDIO6x-FIT license.

Syntax

GtDio6xFileImport (pszInputFile, pszOutputDioFile, nBoardType, bRealtimeCompare, pszImportOptions, pnImportOptionsMaxLen, bWait, phHandle,pszStatus, nStatusMaxLen, pnStatus)

Parameters

Name
Type
Comments
pszInputFile
PCSTR
Specified input WGL, STIL, VCD or eVCD file name.
pszOutputDioFile
PCSTR
Specified output GtDio6x file name. Pass NULL or empty string to this parameter to request the default import options string as explained in the pszImportOptions parameter.
nBoardType
SHORT
Sets the target supported GtDio6x board type:
0x5960 GTDIO6X_BOARD_TYPE_GX5960 – GX5960 GtDio6x board type.
0x5296  GTDIO6X_BOARD_TYPE_GX5296 – GX5296 GtDio6x board type.
bRealtimeCompare
BOOL
If TRUE, then the generated output GtDio6x file will be Real Time compare type.
pszImportOptions
PSTR
Optional buffer to specify or receive import options string (null terminated).
When pszOutputDioFile is not NULL, this parameter specifies the import options such as unused signals, signal direction and cycle-based timing (VCD/eVCD only), this parameter can be NULL. See the section: Importing External Vector Files for more details info and examples of import options string.
When requesting default import options string and pszImportOptions is NULL or the buffer is not large enough to hold the return string then no data is copied and the required buffer size is stored in pnImportOptionsMaxLen. See the section Importing External Vector Files for more details.
pnImportOptionsMaxLen
PSHORT
The size of the import options buffer size. please refer to  section: Importing External Vector Files.
bWait
BOOL
Determine if the function returns immediately or wait until the file import is complete:

 0    The function returns immediately and the import file will be done at the background. In this case the user can check the import file progress using the GtDio6xFileImportGetProgress API.

 1    The function returns only when file import in complete or in case of an error.

Note: If pszOutputDioFile is set to NULL, i.e. the user wants to get back the pszImportOptions string , then bWait is ignored (internally set to TRUE).
phHandle
PHANDLE
If bWait was set to FALSE, the function returns a HANDLE to the file import object. The user can then use that handle to monitor the progress  by polling the GtDio6xFileImportGetProgress API. The returned handle can be used with WaitForSingleObject Windows API to wait until import completed or timed out.
If bWait was set to TRUE, this parameter will be ignored and can be passes as NULL.
pszStatus
PSTR
Buffer to contain the returned error or warning string (null terminated).
nStatusMaxLen
SHORT
Size of the buffer to contain the error or warning string.
pnStatus
PSHORT
Returned status: 0 on success, negative value on failure.

Comments

The function converts the specified file to GtDio6x file format.

Using the pszImportOptions string:

The pszImportOptions string specifed the diffent options for each signal. The options are direction, dependency on other signals for direction and to be use or not in the converted file.

In the following pszImportOptions example string, the MCLK signal is bidirectional and its direction is set to input whenever ACKHW signal is high. Also, MRB is set to be unused in this

Signals]

               MCLK : Bidir  In When [ACKHW 1];

               MRB : Unused Output;

               ACKHW Input;

               AUTOEN;

 [End]

The user can get the pszImportOptions string form the import file API by calling GtDio6xFileImport with the pszOutputDioFile parameter  set to NULL. In that case the function will not convert the input file but instead will fill the pszImportOptions string and pnImportOptionsMaxLen returns the size of the string.

If the user wants  to know the eaxct size of the  returned pszImportOptions string, and have buffer ready for it with the corrct size, then call GtDio6xFileImport with the pszOutputDioFile parameter and pszImportOptions both set to NULL.

Example

Importing a file with bWait=TRUE and using default szImportOptions string:

The following example convert a STIL file to a GX5296 with Real time compare file

 

SHORT nStatus;

CHAR szError[512];

Convert the STIL file to a GtDio6x file.

GtDio6xFileImport (“InputStilFile.stil”, “OutputDioFile.dio6x”, GtDio6x_BOARD_TYPE_GX5296, TRUE, NULL, NULL, TRUE, NULL, szError, sizeof (szError), &nStatus);

 

Importing a file with bWait=TRUE and using szImportOptions string:

The following example convert a STIL file to a GX5296 with Real time compare file using the following steps:

1.  Get the input STIL file szImportOptions string size.

2.  Allocate a buffer with the correct szImportOptions string size.

3.  Convert the STIL file to a GtDio6x file.

 

SHORT nStatus;

SHORT nImportOptionsMaxLen;

CHAR  szError[512];

PCHAR pszImportOptions=NULL;

 

// request the buffer size to receive the default import options string  by passing NULL to  pszOutputDioFile and pszImportOptions

GtDio6xFileImport (“InputStilFile. stil”, NULL, GTDIO6X_BOARD_TYPE_GX5296, TRUE, NULL, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

// Allocate a buffer with the correct szImportOptions string size

pszImportOptions = new char[nImportOptionsMaxLen];

// request the default import options string by passing NULL to pszOutputDioFile

GtDio6xFileImport (“InputStilFile. stil”, NULL, GTDIO6X_BOARD_TYPE_GX5296, TRUE, NULL, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

 

// modify the default import options string, for example, set SignalA to unused …

[Signals]

    SignalA : unused Output;

[End]

// Convert the STIL file to a GtDio6x file using modified import options.

GtDio6xFileImport (“InputStilFile.stil”, “OutputDioFile.dio6x”, GTDIO6X_BOARD_TYPE_GX5296, TRUE, pszImportOptions, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

 

Importing a file with default szImportOptions string and monitoring the profress (bWait=FALSE):

The following example convert a STIL file to a GX5296 with Real time compare file

 

SHORT   nStatus;

CHAR    szStatus[512];

HANDLE  hHandle=NULL;

 

GtDio6xFileImport (“InputStilFile.stil”, “OutputDioFile.dio6x”, GTDIO6X_BOARD_TYPE_GX5296, TRUE, NULL, 0, FALSE, &hHandle, szStatus, sizeof (szStatus), &nStatus);

 

// Monitor the import file process

// Monitor the import file process

while (nStatus>=0)

{  

    GtDio6xFileImportGetProgress(hHandle, FALSE, szStatus, sizeof (szStatus), &nStatus);

    if (nStatus>0)

        printf(“Progress = %i”, (int) nStatus);   // continue

    else

       break;

     // wait for import to finish or time out every 250ms without consuming the CPU

     WaitForSingleObject(hHandle, 250);

}

printf(szStatus);   // print complete (nStatus=0), warning, errrors

 

See Also

GtDio6xFileImportPanel, GtDio6xFileImportGetProgress, GtDio6xGetErrorString