Future Technology Devices
International Ltd.
FTCI2C Programmer's Guide
© Future Technology Devices International Ltd. 2005
I
FTCI2C Programmer's Guide
Table of Contents
Part I Welcome to the FTCI2C
Programmer's Guide
2
Part II I2C Interface Functions
3
1 I2C_GetNumDevices
................................................................................................................................... 4
2 I2C_GetDeviceNameLocID
................................................................................................................................... 5
3 I2C_Open ................................................................................................................................... 6
4 I2C_OpenEx
................................................................................................................................... 7
5 I2C_Close................................................................................................................................... 8
6 I2C_InitDevice
................................................................................................................................... 9
7 I2C_GetClock
................................................................................................................................... 11
8 I2C_SetClock
................................................................................................................................... 12
9 I2C_SetLoopback
................................................................................................................................... 13
10 I2C_SetMode
................................................................................................................................... 14
11 I2C_Write................................................................................................................................... 15
12 I2C_Read................................................................................................................................... 17
13 I2C_GetDllVersion
................................................................................................................................... 19
14 I2C_GetErrorCodeString
................................................................................................................................... 20
21
Part III Appendix
1 Type Definitions
................................................................................................................................... 21
2 FTCI2C.H................................................................................................................................... 23
27
Index
© Future Technology Devices International Ltd. 2005
Welcome to the FTCI2C Programmer's Guide
1
2
Welcome to the FTCI2C Programmer's Guide
The FT2232C device contains FTDI's multi-protocol synchronous serial engine (MPSSE) controller
which may be used to interface to many popular synchronous serial protocols including JTAG, SPI
and I2C.
The FTCI2C DLL has been created to allow application developers to use the FT2232C to create a
USB to Inter-Integrated Circuit (I2C) protocol interface without any knowledge of the MPSSE
command set. All of the functions in FTCI2C.DLL can be replicated using calls to FTD2XX.DLL
and sending the appropriate commands to the MPSSE as per application note AN2232C01 Command Processor For MPSSE and MCU Host Bus Emulation Modes.
The latest version of FTDI's FTCD2XX drivers must be installed to use FTCI2C.DLL as several
calls are made to a new version of FTD2XX.DLL. The MPSSE is available through channel A of
the FT2232C device only; channel B does not support the MPSSE. Channel B may be controlled
independently using FTDI's FTCD2XX drivers while channel A is being used for I2C
communication.
This document lists all of the functions available in FTCI2C.DLL.
The FTCI2C DLL can be downloaded from the FTCI2C page of the MPSSE section in the Projects
area of the site.
© Future Technology Devices International Ltd. 2005
3
2
FTCI2C Programmer's Guide
I2C Interface Functions
The functions listed in this section can be used to set up the FT2232C for I2C communication,
write data to an external device using I2C and read data from an external device using I2C.
Please note that the latest version of FTDI's FTCD2XX drivers must be installed to use the FTCI2C
DLL for I2C communication.
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.1
4
I2C_GetNumDevices
Returns the number of available FT2232C devices connected to a system.
FTC_STATUS I2C_GetNumDevices (lpdwNumDevices)
Parameters
lpdwNumDevices
Pointer to a variable of type DWORD which receives the actual
number of available FT2232C devices connected to a system
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_IO_ERROR
Remarks
This function can be used to provide the maximum index for using with
I2C_GetDeviceNameLocID 5 .
Example
FTC_STATUS Status = FTC_SUCCESS;
DWORD dwNumDevices = 0;
Status = I2C_GetNumDevices(&dwNumDevices);
© Future Technology Devices International Ltd. 2005
5
2.2
FTCI2C Programmer's Guide
I2C_GetDeviceNameLocID
Returns the device name and location ID of an available FT2232C device.
FTC_STATUS I2C_GetDeviceNameLocID (DWORD dwDeviceNameIndex, LPSTR
lpDeviceNameBuffer, DWORD dwBufferSize,
LPDWORD lpdwLocationID)
Parameters
dwDeviceNameIndex
lpDeviceNameBuffer
dwBufferSize
lpdwLocationID
Index of the FT2232C device.
Pointer to buffer that receives the device name of the specified
FT2232C device connected to a system. The string will be
NULL terminated.
Length of the buffer created for the device name string. Set
buffer length to a minimum of 50 characters.
Pointer to a variable of type DWORD which receives the
location identifier of the specified FT2232C device.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_DEVICE_NOT_FOUND
FTC_INVALID_DEVICE_NAME_INDEX
FTC_NULL_ DEVICE_NAME_BUFFER_POINTER
FTC_ DEVICE_NAME_BUFFER_TOO_SMALL
FTC_IO_ERROR
Remarks
The I2C_GetNumDevices 4 function can be used to obtain the number of available FT2232C
devices connected to a system. The device index is 0 based. The information returned from this
function can be used with I2C_OpenEx 7 to open a specific device.
Please note that Windows CE does not support location IDs. In the Windows CE FTCI2C DLL,
devices can be identified by serial number using the lpDeviceNameBuffer. lpdwLocationID is
undefined in this case.
Example
FTC_STATUS Status = FTC_SUCCESS;
char szDeviceName[100];
DWORD dwLocationID = 0;
Status = I2C_GetDeviceNameLocID(0, szDeviceName, 100, &dwLocationID);
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.3
6
I2C_Open
Open the device and return a handle that will be used for subsequent accesses. This function can
only be used when there is a single FT2232C device connected.
FTC_STATUS I2C_Open (FTC_HANDLE *pftHandle)
Parameters
*pftHandle
Pointer to a variable of type FTC_HANDLE where the handle to
the open device will be returned. This handle must then be
used in all subsequent calls to access this device.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_DEVICE_NOT_FOUND
FTC_DEVICE_IN_USE
FTC_TOO_MANY_DEVICES
FTC_FAILED_TO_SYNCHRONIZE_DEVICE_MPSSE
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
FTC_INSUFFICIENT_RESOURCES
Remarks
If more than one device is attached, this function will return an error code. For multiple devices,
use I2C_GetDeviceNameLocID 5 and then I2C_OpenEx 7 instead.
Example
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
Status = I2C_Open(&ftHandle);
© Future Technology Devices International Ltd. 2005
7
2.4
FTCI2C Programmer's Guide
I2C_OpenEx
Open the specified device and return a handle that will be used for subsequent accesses. The
device must be specified by its device description and location.
FTC_STATUS I2C_OpenEx (LPSTR lpDeviceName, DWORD dwLocationID, FTC_HANDLE
*pftHandle)
Parameters
lpDeviceName
dwLocationID
*pftHandle
Pointer to a NULL terminated string that contains the name of
the specified FT2232C device to be opened.
Specifies the location identifier of the specified FT2232C
device to be opened.
Pointer to a variable of type FTC_HANDLE where the handle to
the open device will be returned. This handle must then be
used in all subsequent calls to access this device.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_NULL_DEVICE_NAME_BUFFER_POINTER
FTC_INVALID_DEVICE_NAME
FTC_INVALID_LOCATION_ID
FTC_DEVICE_NOT_FOUND
FTC_DEVICE_IN_USE
FTC_FAILED_TO_SYNCHRONIZE_DEVICE_MPSSE
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
FTC_INSUFFICIENT_RESOURCES
Remarks
The device name and location ID parameters are returned from the I2C_GetDeviceNameLocID
function.
5
Please note that Windows CE does not support location IDs. In the Windows CE FTCI2C DLL,
devices can be identified by serial number using the lpDeviceName. dwLocationID is unused in
this case.
Example
FTC_STATUS Status = FTC_SUCCESS;
char szDeviceName[100];
DWORD dwLocationID = 0;
FTC_HANDLE ftHandle;
Status = I2C_OpenEx(szDeviceName, dwLocationID, &ftHandle);
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.5
8
I2C_Close
Close an open device.
FTC_STATUS I2C_Close (FTC_HANDLE ftHandle)
Parameters
ftHandle
Handle of the device.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_IO_ERROR
Example
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
Status = I2C_Close(ftHandle);
© Future Technology Devices International Ltd. 2005
9
2.6
FTCI2C Programmer's Guide
I2C_InitDevice
Initialise the device.
FTC_STATUS I2C_InitDevice (FTC_HANDLE ftHandle, DWORD dwClockDivisor)
Parameters
ftHandle
dwClockDivisor
Handle of the device.
Specifies a clock divisor which will be used to set the frequency
for clocking data in and out of the FT2232C device.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_INVALID_CLOCK_DIVISOR
FTC_FAILED_TO_SYNCHRONIZE_DEVICE_MPSSE
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
FTC_INSUFFICIENT_RESOURCES
Remarks
This function initializes the FT2232C device, by carrying out the following:
·
·
·
·
·
·
·
·
·
·
·
·
resets the device and purge device USB input buffer
sets the device USB input and output buffers to 64K bytes
sets the special characters for the device, disable event and error characters
sets the device read timeout to infinite
sets the device write timeout to 5 seconds
sets the device latency timer to 16 milliseconds
reset MPSSE controller
enable MPSSE controller
synchronize to the MPSSE controller
set data in and data out clock frequency
set MPSSE loopback state to off (default)
ensure the device USB input buffer is empty
The valid range for dwClockDivisor is 0 to 65535. The highest clock frequency is represented by 0,
which is equivalent to 6MHz and the lowest clock frequency is represented by 65535, which is
equivalent to 91Hz. This can be calculated using the following formula:
Clock Frequency = 12MHz / ((1 + dwClockDivisor) * 2)
Example
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
DWORD dwClockDivisor = 0;
Status = I2C_InitDevice(ftHandle, dwClockDivisor);
© Future Technology Devices International Ltd. 2005
10
11
2.7
FTCI2C Programmer's Guide
I2C_GetClock
Calculates the actual frequency in Hz for a given clock divisor value.
FTC_STATUS I2C_GetClock (DWORD dwClockDivisor, LPDWORD lpdwClockFrequencyHz)
Parameters
dwClockDivisor
lpdwClockFrequencyHz
Specifies a clock divisor which will be used to calculate the
frequency for clocking data in and out of the FT2232C device.
Pointer to a variable of type DWORD which receives the actual
frequency in Hz that data will be clocked in and out of the
FT2232C device at.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_CLOCK_DIVISOR
Remarks
The valid range for dwClockDivisor is 0 to 65535. The highest clock frequency is represented by 0
which is equivalent to 6MHz and the lowest clock frequency is represented by 65535 which is
equivalent to 91Hz. This can be calculated using the following formula:
dwClockFrequency = 12MHz / ((1 + dwClockDivisor) * 2)
The clock frequency can be set by passing the clock divisor value to I2C_SetClock
I2C_InitDevice 9 .
12
or
Example
FTC_STATUS Status = FTC_SUCCESS;
DWORD dwClockDivisor = 0;
DWORD dwClockFrequencyHz = 0;
Status = I2C_GetClock(dwClockDivisor, &dwClockFrequencyHz);
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.8
12
I2C_SetClock
Sets the clock divisor value and returns the clock frequency in Hz.
FTC_STATUS I2C_SetClock (FTC_HANDLE ftHandle, DWORD dwClockDivisor, LPDWORD
lpdwClockFrequencyHz)
Parameters
ftHandle
dwClockDivisor
lpdwClockFrequencyHz
Handle of the device.
Specifies a clock divisor which will be used to set the frequency
for clocking data in and out of the FT2232C device.
Pointer to a variable of type DWORD which receives the actual
frequency in Hz that data will be clocked in and out of the
FT2232C device at.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_INVALID_CLOCK_DIVISOR
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
Remarks
The valid range for dwClockDivisor is 0 to 65535. The highest clock frequency is represented by 0
which is equivalent to 6MHz and the lowest clock frequency is represented by 65535 which is
equivalent to 91Hz. This can be calculated using the following formula:
dwClockFrequency = 12MHz / ((1 + dwClockDivisor) * 2)
I2C_SetClock 12 will return the actual frequency in Hz for the current divisor value. The clock
frequancy in Hz can also be calculated using I2C_GetClock 11 .
Example
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
DWORD dwClockDivisor = 0;
DWORD dwClockFrequencyHz = 0;
Status = I2C_SetClock(ftHandle, dwClockDivisor, &dwClockFrequencyHz);
© Future Technology Devices International Ltd. 2005
13
2.9
FTCI2C Programmer's Guide
I2C_SetLoopback
Enables or disables loop back mode.
FTC_STATUS I2C_SetLoopback (FTC_HANDLE ftHandle, BOOL bLoopbackState)
Parameters
ftHandle
bLoopbackState
Handle of the device.
Controls the state of the FT2232C device loopback, to turn
loopback on (TRUE) or off (FALSE).
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
Remarks
Loop back mode will simply return any data written to the device. Loop back mode can be enabled
by setting bLoopbackState to true, or disabled by setting bLoopbackState to false. The default
state for the loop back mode is disabled.
Example
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
Status = I2C_SetLoopback(ftHandle, true);
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.10
14
I2C_SetMode
Sets the I2C communications mode.
FTC_STATUS I2C_SetMode (FTC_HANDLE ftHandle, DWORD dwCommsMode)
Parameters
ftHandle
dwCommsMode
Handle of the device.
Specifies the communications mode of an external device.
Valid values are STANDARD_MODE, FAST_MODE and
STRETCH_DATA_MODE.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_COMMS_MODE
Remarks
The default value for dwCommsMode is FAST_MODE.
© Future Technology Devices International Ltd. 2005
15
2.11
FTCI2C Programmer's Guide
I2C_Write
Write data from the FT2232C to an external device using the I2C protocol.
FTC_STATUS I2C_Write (FTC_HANDLE ftHandle, PWriteControlByteBuffer
pWriteControlBuffer, DWORD dwNumControlBytesToWrite, BOOL
bControlAcknowledge, DWORD dwControlAckTimeoutmSecs, BOOL
bStopCondition, DWORD dwDataWriteTypes, PWriteDataByteBuffer
pWriteDataBuffer, DWORD dwNumDataBytesToWrite, BOOL
bDataAcknowledge, DWORD dwDataAckTimeoutmSecs,
PFTC_PAGE_WRITE_DATA pPageWriteData)
Parameters
ftHandle
pWriteControlBuffer
dwNumControlBytesToWrite
bControlAcknowledge
dwControlAckTimeoutmSecs
bStopCondition
dwWriteTypes
pWriteDataBuffer
dwNumDataBytesToWrite
bDataAcknowledge
dwDataAckTimeoutmSecs
pPageWriteData
Handle of the device.
Pointer to buffer that contains the control and address data to
be written to an external device.
Number of bytes in the write control buffer to be written to an
external device. Valid range 1 to 255 bytes.
Check for acknowledgement after every control byte is written
to an external device (TRUE) or do not check for
acknowledgement after every control byte is written to an
external device (FALSE).
Timeout in milliseconds to wait for an acknowledgement after a
control byte has been written to an external device. A value of
INFINITE indicates timeout never expires while waiting for an
acknowledgement. Only valid if bControlAcknowledge is
TRUE.
Send a Stop condition (TRUE) or do not send a Stop condition
(FALSE) after all control bytes have been written to an external
device.
Specifies the type of write to be used when the data contained
in the write data buffer is written to an external device. Write
no data (NO_WRITE_TYPE), write the data one byte at a time
(BYTE_WRITE_TYPE) or write the data in pages
(PAGE_WRITE_TYPE).
Pointer to buffer that contains the data to be written to an
external device.
Number of bytes in the write data buffer which contain all the
specified bits to be written to the external device. Valid range
is 1 to 65535 bytes. If NO_BYTE_WRITE is specified, no data
will be written to an external device. If BYTE_WRITE_TYPE is
specified, only one byte will be written to an external device.
Check for acknowledgement after every data byte is written to
an external device (TRUE) or do not check for
acknowledgement after every data byte is written to an external
device (FALSE).
Timeout in milliseconds to wait for an acknowledgement after a
data byte has been written to an external device. A value of
INFINITE indicates timeout never expires while waiting for an
acknowledgement. Only valid if bDataAcknowledge is TRUE.
Pointer to a structure that contains the number of pages and
the number of bytes per page to be written to an external
device.
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
16
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_NULL_CONTROL_DATA_BUFFER_POINTER
FTC_INVALID_NUMBER_CONTROL_BYTES
FTC_CONTROL_ACKNOWLEDGE_TIMEOUT
FTC_NULL_WRITE_DATA_BUFFER_POINTER
FTC_INVALID_NUMBER_DATA_BYTES_WRITE
FTC_DATA_ACKNOWLEDGE_TIMEOUT
FTC_INVALID_WRITE_TYPE
FTC_NUMBER_BYTES_TOO_SMALL_PAGE_WRITE
FTC_NULL_PAGE_WRITE_BUFFER_POINTER
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
Remarks
This function will write data from the FT2232C to an external device using the I2C protocol. The
data will be clocked at a rate specified by the clock divisor set by calling either the
I2C_InitDevice 9 or I2C_SetClock 12 functions.
The write control buffer, write data buffer and page write data definitions are given in the
Appendix 21 .
Example
#define MAX_I2C_M24C64_CHIP_SIZE_IN_BYTES 512
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
DWORD DataWriteType = 0;
DWORD dwWriteDataBufferIndex = 0;
WriteControlByteBuffer WriteControlBuffer;
WriteDataByteBuffer WriteDataBuffer;
DWORD dwNumDataBytesToWrite = 0;
FTC_PAGE_WRITE_DATA PageWriteData;
DWORD dwWriteDataByteAddress = 0;
DWORD Index = 0;
// Example for M24C64 EEPROM
WriteControlBuffer[0] = '\xAE'; //1 0 1 0 A2 A1 A0 0 - device address 7
for (Index = 0; Index < MAX_I2C_M24C64_CHIP_SIZE_IN_BYTES; Index++)
WriteDataBuffer[Index] = '\xFF'; // Erase address locations
dwWriteDataByteAddress = 0;
// shift down by 8 bits
WriteControlBuffer[1] = ((dwWriteDataByteAddress >> 8) & '\xFF');
WriteControlBuffer[2] = (dwWriteDataByteAddress & '\xFF');
Status = I2C_Write(ftHandle, &WriteControlBuffer, 3, true, 20, true, BYTE_WRITE_TYPE,
&WriteDataBuffer, MAX_I2C_M24C64_CHIP_SIZE_IN_BYTES, true, 20, &PageWriteData);
© Future Technology Devices International Ltd. 2005
17
2.12
FTCI2C Programmer's Guide
I2C_Read
Read data from an external device to the FT2232C using the I2C protocol.
FTC_STATUS I2C_Read (FTC_HANDLE ftHandle, PWriteControlByteBuffer
pWriteControlBuffer, DWORD dwNumControlBytesToWrite, BOOL
bControlAcknowledge, DWORD dwControlAckTimeoutmSecs,
DWORD dwReadTypes, PReadDataByteBuffer pReadDataBuffer,
DWORD dwNumDataBytesToRead)
Parameters
ftHandle
pWriteControlBuffer
dwNumControlBytesToWrite
bControlAcknowledge
dwControlAckTimeoutmSecs
dwReadTypes
pReadDataBuffer
dwNumDataBytesToRead
Handle of the device.
Pointer to buffer that contains the control and address data to
be written to an external device.
Number of bytes in the write control buffer to be written to an
external device. Valid range 1 to 255 bytes.
Check for acknowledgement after every control byte is written
to an external device (TRUE) or do not check for
acknowledgement after every control byte is written to an
external device (FALSE).
Timeout in milliseconds to wait for an acknowledgement after a
control byte has been written to an external device. A value of
INFINITE indicates timeout never expires while waiting for an
acknowledgement. Only valid if bControlAcknowledge is
TRUE.
Specifies the type of read to be used when the data contained
in the read data buffer is read from an external device. Read
the data one byte at a time (BYTE_READ_TYPE) or read the
data in a continuous block (BLOCK_READ_TYPE).
Pointer to buffer that contains the data to be read from an
external device.
Number of bytes to be read from an external device. Valid
range 1 to 65535 bytes. If BYTE_READ_TYPE specified, only
one byte will be returned in the read data buffer.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_INVALID_HANDLE
FTC_NULL_CONTROL_DATA_BUFFER_POINTER
FTC_INVALID_NUMBER_CONTROL_BYTES
FTC_CONTROL_ACKNOWLEDGE_TIMEOUT
FTC_NULL_READ_DATA_BUFFER_POINTER
FTC_INVALID_NUMBER_DATA_BYTES_READ
FTC_INVALID_READ_TYPE
FTC_FAILED_TO_COMPLETE_COMMAND
FTC_IO_ERROR
Remarks
This function will read data from an external device to the FT2232C using the I2C protocol. The
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
data will be clocked at a rate specified by the clock divisor set by calling either the
I2C_InitDevice 9 or I2C_SetClock 12 functions.
The write control buffer and read data buffer definitions are given in the Appendix
Example
#define MAX_I2C_M24C64_CHIP_SIZE_IN_BYTES 512
FTC_STATUS Status = FTC_SUCCESS;
FTC_HANDLE ftHandle;
BYTE DataByte = 0;
WriteControlByteBuffer WriteControlBuffer;
DWORD DataReadType = 0;
ReadDataByteBuffer ReadDataBuffer;
DWORD dwNumDataBytesToRead = 0;
DWORD dwReadDataByteAddress = 0;
// Example for M24C64 EEPROM
WriteControlBuffer[0] = '\xAF'; //1 0 1 0 A2 A1 A0 1 - device address 7
dwReadDataByteAddress = 0;
DataReadType = BYTE_READ_TYPE; //BLOCK_READ_TYPE; //
if (DataReadType == BYTE_READ_TYPE)
dwNumDataBytesToRead = 1;
else
dwNumDataBytesToRead = MAX_I2C_M24C64_CHIP_SIZE_IN_BYTES;
// shift down by 8 bits
WriteControlBuffer[1] = ((dwReadDataByteAddress >> 8) & '\xFF');
WriteControlBuffer[2] = (dwReadDataByteAddress & '\xFF');
Status = I2C_Read(ftHandle, &WriteControlBuffer, 3, true, 20, DataReadType,
&ReadDataBuffer, dwNumDataBytesToRead);
© Future Technology Devices International Ltd. 2005
21
.
18
19
2.13
FTCI2C Programmer's Guide
I2C_GetDllVersion
Returns the version number of the current FTC_I2C DLL.
FTC_STATUS I2C_GetDllVersion (LPSTR lpDllVersionBuffer, DWORD dwBufferSize)
Parameters
lpDllVersionBuffer
dwBufferSize
Pointer to the buffer that receives the version of this DLL. The
string will be NULL terminated.
Length of the buffer created for the device name string. Set
buffer length to a minimum of 10 characters.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_NULL_DLL_VERSION_BUFFER_POINTER
FTC_DLL_VERSION_BUFFER_TOO_SMALL
Example
FTC_STATUS Status = FTC_SUCCESS;
char szDllVersion[10];
Status = I2C_GetDllVersion(szDllVersion, 10);
© Future Technology Devices International Ltd. 2005
I2C Interface Functions
2.14
20
I2C_GetErrorCodeString
Provides an explanation of an error code.
FTC_STATUS I2C_GetErrorCodeString (LPSTR lpLanguage, FTC_STATUS StatusCode,
LPSTR lpErrorMessageBuffer, DWORD dwBufferSize)
Parameters
lpLanguage
StatusCode
lpErrorMessageBuffer
dwBufferSize
Pointer to a NULL terminated string that contains the language
code. Default for this first version the default language will be
English (EN).
Status code returned from a previous FTC_I2C DLL function
call.
Pointer to the buffer that receives the error code explanation
string.
Length of the buffer created for the error code explanation
string. Set buffer length to a minimum of 100 characters.
Return Value
FTC_SUCCESS if successful, otherwise the return value is one of the following FTC error codes:
FTC_NULL_LANGUAGE_CODE_BUFFER_POINTER
FTC_INVALID_LANGUAGE_CODE
FTC_INVALID_STATUS_CODE
FTC_NULL_ERROR_MESSAGE_BUFFER_POINTER
FTC_ERROR_MESSAGE_BUFFER_TOO_SMALL
Example
FTC_STATUS Status = FTC_SUCCESS;
char szErrorMessage[100];
Status = I2C_GetErrorCodeString("EN", Status, szErrorMessage, 100);
© Future Technology Devices International Ltd. 2005
21
FTCI2C Programmer's Guide
3
Appendix
3.1
Type Definitions
For Visual C++ applications, these values are pre-declared in the header file (FTCI2C.H 23 ), which
is included in the driver release. For other languages, these definitions will have to be converted to
use equivalent types and may have to be defined in an include file or within the body of the code.
DWORD
LPDWORD
BOOL
LPSTR
FTC_HANDLE
Unsigned long (4 bytes)
Long pointer to a DWORD value
Boolean value (4 bytes)
Long pointer to a NULL terminated string
DWORD
FTC_STATUS (DWORD)
FTC_SUCCESS = 0
FTC_INVALID_HANDLE = 1
FTC_DEVICE_NOT_FOUND = 2
FTC_DEVICE_NOT_OPENED = 3
FTC_IO_ERROR = 4
FTC_INSUFFICIENT_RESOURCES = 5
FTC_FAILED_TO_COMPLETE_COMMAND = 20
FTC_FAILED_TO_SYNCHRONIZE_DEVICE_MPSSE = 21
FTC_INVALID_DEVICE_NAME_INDEX = 22
FTC_NULL_DEVICE_NAME_BUFFER_POINTER = 23
FTC_DEVICE_NAME_BUFFER_TOO_SMALL = 24
FTC_INVALID_DEVICE_NAME = 25
FTC_INVALID_LOCATION_ID = 26
FTC_DEVICE_IN_USE = 27
FTC_TOO_MANY_DEVICES = 28
FTC_EXTERNAL_DEVICE_NOT_FOUND = 29
FTC_INVALID_CLOCK_DIVISOR = 30
FTC_NULL_CONTROL_DATA_BUFFER_POINTER = 31
FTC_INVALID_NUMBER_CONTROL_BYTES = 32
FTC_CONTROL_ACKNOWLEDGE_TIMEOUT = 33
FTC_NULL_WRITE_DATA_BUFFER_POINTER = 34
FTC_INVALID_NUMBER_DATA_BYTES_WRITE = 35
FTC_DATA_ACKNOWLEDGE_TIMEOUT = 36
FTC_INVALID_WRITE_TYPE = 37
FTC_NUMBER_BYTES_TOO_SMALL_PAGE_WRITE = 38
FTC_NULL_PAGE_WRITE_BUFFER_POINTER = 39
FTC_NULL_READ_DATA_BUFFER_POINTER = 40
FTC_INVALID_NUMBER_DATA_BYTES_READ = 41
FTC_INVALID_READ_TYPE = 42
FTC_NULL_DLL_VERSION_BUFFER_POINTER = 43
FTC_DLL_VERSION_BUFFER_TOO_SMALL = 44
FTC_NULL_LANGUAGE_CODE_BUFFER_POINTER = 45
FTC_NULL_ERROR_MESSAGE_BUFFER_POINTER = 46
FTC_ERROR_MESSAGE_BUFFER_TOO_SMALL = 47
FTC_INVALID_LANGUAGE_CODE = 48
FTC_INVALID_STATUS_CODE = 49
© Future Technology Devices International Ltd. 2005
Appendix
FTC_PAGE_WRITE_DATA
typedef struct FTC_Page_Write_Data{
DWORD dwNumPages;
DWORD dwNumBytesPerPage;
}FTC_PAGE_WRITE_DATA, *PFTC_PAGE_WRITE_DATA;
WRITE CONTROL BYTE BUFFER
#define MAX_WRITE_CONTROL_BYTES_BUFFER_SIZE 256 // 256 bytes
typedef BYTE WriteControlByteBuffer[MAX_WRITE_CONTROL_BYTES_BUFFER_SIZE];
typedef WriteControlByteBuffer *PWriteControlByteBuffer;
WRITE DATA BYTE BUFFER
#define MAX_WRITE_DATA_BYTES_BUFFER_SIZE 65536 // 64k bytes
typedef BYTE WriteDataByteBuffer[MAX_WRITE_DATA_BYTES_BUFFER_SIZE];
typedef WriteDataByteBuffer *PWriteDataByteBuffer;
READ DATA BYTE BUFFER
#define MAX_READ_DATA_BYTES_BUFFER_SIZE 65536 // 64k bytes
typedef BYTE ReadDataByteBuffer[MAX_READ_DATA_BYTES_BUFFER_SIZE];
typedef ReadDataByteBuffer *PReadDataByteBuffer;
© Future Technology Devices International Ltd. 2005
22
23
3.2
FTCI2C Programmer's Guide
FTCI2C.H
/*++
Copyright (c) 2005 Future Technology Devices International Ltd.
Module Name:
ftcjtag.h
Abstract:
API DLL for FT2232C Dual Device setup to simulate the I2C synchronous protocol.
FTCI2C library definitions
Environment:
kernel & user mode
Revision History:
23/03/05
kra
Created.
--*/
#ifndef FTCI2C_H
#define FTCI2C_H
// The following ifdef block is the standard way of creating macros
// which make exporting from a DLL simpler. All files within this DLL
// are compiled with the FTCI2C_EXPORTS symbol defined on the command line.
// This symbol should not be defined on any project that uses this DLL.
// This way any other project whose source files include this file see
// FTCI2C_API functions as being imported from a DLL, whereas this DLL
// sees symbols defined with this macro as being exported.
#ifdef FTCI2C_EXPORTS
#define FTCI2C_API __declspec(dllexport)
#else
#define FTCI2C_API __declspec(dllimport)
#endif
typedef DWORD FTC_HANDLE;
typedef ULONG FTC_STATUS;
#define NO_WRITE_TYPE 0
#define BYTE_WRITE_TYPE 1
#define PAGE_WRITE_TYPE 2
#define BYTE_READ_TYPE 1
#define BLOCK_READ_TYPE 2
#define STANDARD_MODE 1
#define FAST_MODE 2
#define STRETCH_DATA_MODE 4
© Future Technology Devices International Ltd. 2005
Appendix
#define FTC_SUCCESS 0 // FT_OK
#define FTC_INVALID_HANDLE 1 // FT_INVALID_HANDLE
#define FTC_DEVICE_NOT_FOUND 2 //FT_DEVICE_NOT_FOUND
#define FTC_DEVICE_NOT_OPENED 3 //FT_DEVICE_NOT_OPENED
#define FTC_IO_ERROR 4 //FT_IO_ERROR
#define FTC_INSUFFICIENT_RESOURCES 5 // FT_INSUFFICIENT_RESOURCES
#define FTC_FAILED_TO_COMPLETE_COMMAND 20
#define FTC_FAILED_TO_SYNCHRONIZE_DEVICE_MPSSE 21
#define FTC_INVALID_DEVICE_NAME_INDEX 22
#define FTC_NULL_DEVICE_NAME_BUFFER_POINTER 23
#define FTC_DEVICE_NAME_BUFFER_TOO_SMALL 24
#define FTC_INVALID_DEVICE_NAME 25
#define FTC_INVALID_LOCATION_ID 26
#define FTC_DEVICE_IN_USE 27
#define FTC_TOO_MANY_DEVICES 28
#define FTC_EXTERNAL_DEVICE_NOT_FOUND 29
#define FTC_INVALID_CLOCK_DIVISOR 30
#define FTC_NULL_CONTROL_DATA_BUFFER_POINTER 31
#define FTC_INVALID_NUMBER_CONTROL_BYTES 32
#define FTC_CONTROL_ACKNOWLEDGE_TIMEOUT 33
#define FTC_NULL_WRITE_DATA_BUFFER_POINTER 34
#define FTC_INVALID_NUMBER_DATA_BYTES_WRITE 35
#define FTC_DATA_ACKNOWLEDGE_TIMEOUT 36
#define FTC_INVALID_WRITE_TYPE 37
#define FTC_NUMBER_BYTES_TOO_SMALL_PAGE_WRITE 38
#define FTC_NULL_PAGE_WRITE_BUFFER_POINTER 39
#define FTC_NULL_READ_DATA_BUFFER_POINTER 40
#define FTC_INVALID_NUMBER_DATA_BYTES_READ 41
#define FTC_INVALID_READ_TYPE 42
#define FTC_INVALID_COMMS_MODE 43
#define FTC_NULL_DLL_VERSION_BUFFER_POINTER 44
#define FTC_DLL_VERSION_BUFFER_TOO_SMALL 45
#define FTC_NULL_LANGUAGE_CODE_BUFFER_POINTER 46
#define FTC_NULL_ERROR_MESSAGE_BUFFER_POINTER 47
#define FTC_ERROR_MESSAGE_BUFFER_TOO_SMALL 48
#define FTC_INVALID_LANGUAGE_CODE 49
#define FTC_INVALID_STATUS_CODE 50
#ifdef __cplusplus
extern "C" {
#endif
FTCI2C_API
FTC_STATUS WINAPI I2C_GetNumDevices(LPDWORD lpdwNumDevices);
FTCI2C_API
FTC_STATUS WINAPI I2C_GetDeviceNameLocID(DWORD dwDeviceNameIndex, LPSTR
lpDeviceNameBuffer, DWORD dwBufferSize, LPDWORD lpdwLocationID);
FTCI2C_API
FTC_STATUS WINAPI I2C_OpenEx(LPSTR lpDeviceName, DWORD dwLocationID,
FTC_HANDLE *pftHandle);
FTCI2C_API
FTC_STATUS WINAPI I2C_Open(FTC_HANDLE *pftHandle);
FTCI2C_API
© Future Technology Devices International Ltd. 2005
24
25
FTCI2C Programmer's Guide
FTC_STATUS WINAPI I2C_Close(FTC_HANDLE ftHandle);
FTCI2C_API
FTC_STATUS WINAPI I2C_InitDevice(FTC_HANDLE ftHandle, DWORD dwClockDivisor);
FTCI2C_API
FTC_STATUS WINAPI I2C_GetClock(DWORD dwClockDivisor, LPDWORD
lpdwClockFrequencyHz);
FTCI2C_API
FTC_STATUS WINAPI I2C_SetClock(FTC_HANDLE ftHandle, DWORD dwClockDivisor,
LPDWORD lpdwClockFrequencyHz);
FTCI2C_API
FTC_STATUS WINAPI I2C_SetLoopback(FTC_HANDLE ftHandle, BOOL bLoopbackState);
FTCI2C_API
FTC_STATUS WINAPI I2C_SetMode(FTC_HANDLE ftHandle, DWORD dwCommsMode);
#define MAX_WRITE_CONTROL_BYTES_BUFFER_SIZE 256
// 256 bytes
typedef BYTE WriteControlByteBuffer[MAX_WRITE_CONTROL_BYTES_BUFFER_SIZE];
typedef WriteControlByteBuffer *PWriteControlByteBuffer;
typedef struct FTC_Page_Write_Data{
DWORD dwNumPages;
DWORD dwNumBytesPerPage;
}FTC_PAGE_WRITE_DATA, *PFTC_PAGE_WRITE_DATA;
#define MAX_WRITE_DATA_BYTES_BUFFER_SIZE 65536
// 64k bytes
typedef BYTE WriteDataByteBuffer[MAX_WRITE_DATA_BYTES_BUFFER_SIZE];
typedef WriteDataByteBuffer *PWriteDataByteBuffer;
FTCI2C_API
FTC_STATUS WINAPI I2C_Write(FTC_HANDLE ftHandle, PWriteControlByteBuffer
pWriteControlBuffer,
DWORD dwNumControlBytesToWrite, BOOL bControlAcknowledge, DWORD
dwControlAckTimeoutmSecs,
BOOL bStopCondition, DWORD dwDataWriteTypes, PWriteDataByteBuffer
pWriteDataBuffer, DWORD dwNumDataBytesToWrite,
BOOL bDataAcknowledge, DWORD dwDataAckTimeoutmSecs,
PFTC_PAGE_WRITE_DATA pPageWriteData);
#define MAX_READ_DATA_BYTES_BUFFER_SIZE 65536
// 64k bytes
typedef BYTE ReadDataByteBuffer[MAX_READ_DATA_BYTES_BUFFER_SIZE];
typedef ReadDataByteBuffer *PReadDataByteBuffer;
FTCI2C_API
FTC_STATUS WINAPI I2C_Read(FTC_HANDLE ftHandle, PWriteControlByteBuffer
pWriteControlBuffer,
DWORD dwNumControlBytesToWrite, BOOL bControlAcknowledge, DWORD
dwControlAckTimeoutmSecs,
DWORD dwDataReadTypes, PReadDataByteBuffer pReadDataBuffer, DWORD
dwNumDataBytesToRead);
FTCI2C_API
© Future Technology Devices International Ltd. 2005
Appendix
26
FTC_STATUS WINAPI I2C_GetDllVersion(LPSTR lpDllVersionBuffer, DWORD dwBufferSize);
FTCI2C_API
FTC_STATUS WINAPI I2C_GetErrorCodeString(LPSTR lpLanguage, FTC_STATUS StatusCode,
LPSTR lpErrorMessageBuffer, DWORD dwBufferSize);
#ifdef __cplusplus
}
#endif
#endif /* FTCI2C_H */
© Future Technology Devices International Ltd. 2005
27
FTCI2C Programmer's Guide
Index
-FFT2232C 2
FTCI2C Programmer's Guide
FTCI2C.H 23
2
-II2C 2
I2C_Close 8
I2C_GetClock 11
I2C_GetDeviceNameLocID 5
I2C_GetDllVersion 19
I2C_GetErrorCodeString 20
I2C_GetNumDevices 4
I2C_InitDevice 9
I2C_Open 6
I2C_OpenEx 7
I2C_Read 17
I2C_SetClock 12
I2C_SetLoopback 13
I2C_SetMode 14
I2C_Write 15
Introduction 2
-MMPSSE
2
-TType Definitions
21
-WWelcome
2
© Future Technology Devices International Ltd. 2005