AN_365 FT900 API Programmers Manual

Application Note
AN_365
FT900 API Programmers Manual
Version 1.2
Issue Date: 2016-02-25
This document describes the API for the FT900 Peripheral Driver Library.
Use of FTDI devices in life support and/or safety applications is entirely at the user’s risk, and the
user agrees to defend, indemnify and hold FTDI harmless from any and all damages, claims, suits
or expense resulting from such use.
Future Technology Devices International Limited (FTDI)
Unit 1, 2 Seaward Place, Glasgow G41 1HH, United Kingdom
Tel.: +44 (0) 141 429 2777 Fax: + 44 (0) 141 429 2758
Web Site: http://ftdichip.com
Copyright © Future Technology Devices International Limited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Table of Contents
1 Introduction ............................................................ 6
1.1 Overview.......................................................................... 6
2 libft900.a Library..................................................... 7
2.1 Chip management............................................................. 7
2.1.1
API Cross Reference ............................................................................................... 7
2.1.2
Enumeration Type Documentation .......................................................................... 7
2.1.3
Function Documentation ......................................................................................... 9
2.2 Delay functions .............................................................. 11
2.2.1
API Cross Reference ............................................................................................. 11
2.2.2
Macro Definition Documentation ........................................................................... 11
2.3 Interrupt Management.................................................... 12
2.3.1
API Cross Reference ............................................................................................. 12
2.3.2
Macro Definition Documentation ........................................................................... 12
2.3.3
Typedef Documentation........................................................................................ 12
2.3.4
Enumeration Type Documentation ........................................................................ 12
2.3.5
Function Documentation ....................................................................................... 13
2.4 General Purpose I/O and Pad Control.............................. 15
2.4.1
API Cross Reference ............................................................................................. 15
2.4.2
Function to Pad Mappings ..................................................................................... 15
2.4.3
Enumeration Type Documentation ........................................................................ 17
2.4.4
Function Documentation ....................................................................................... 24
2.5 Assembler Definitions ..................................................... 29
2.5.1
API Cross Reference ............................................................................................. 29
2.5.2
Macro Documentation........................................................................................... 29
2.5.3
Function Documentation ....................................................................................... 33
2.6 Watchdog Timer ............................................................. 34
2.6.1
API Cross Reference ............................................................................................. 34
2.6.2
Enumeration Type Documentation ........................................................................ 34
2.6.3
Function Documentation ....................................................................................... 35
2.7 Timers............................................................................ 36
2.7.1
API Cross Reference ............................................................................................. 36
1
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.7.2
Enumeration Type Documentation ........................................................................ 36
2.7.3
Function Documentation ....................................................................................... 37
2.8 Analogue to Digital Converter ......................................... 40
2.8.1
API Cross Reference ............................................................................................. 40
2.8.2
Enumeration Type Documentation ........................................................................ 40
2.8.3
Function Documentation ....................................................................................... 40
2.9 Digital to Analogue Converter ......................................... 43
2.9.1
API Cross Reference ............................................................................................. 43
2.9.2
Enumeration Type Documentation ........................................................................ 43
2.9.3
Function Documentation ....................................................................................... 43
2.10
Ethernet driver............................................................. 47
2.10.1
API Cross Reference ............................................................................................. 47
2.10.2
Enumeration Type Documentation ........................................................................ 47
2.10.3
Function Documentation ....................................................................................... 47
2.11
UART ........................................................................... 51
2.11.1
API Cross Reference ............................................................................................. 51
2.11.2
Macro Definition Documentation ........................................................................... 51
2.11.3
Enumeration Type Documentation ........................................................................ 52
2.11.4
Function Documentation ....................................................................................... 53
2.12
I2C Master.................................................................... 59
2.12.1
API Cross Reference ............................................................................................. 59
2.12.2
Enumeration Type Documentation ........................................................................ 59
2.12.3
Function Documentation ....................................................................................... 59
2.13
I2C Slave ...................................................................... 62
2.13.1
API Cross Reference ............................................................................................. 62
2.13.2
Function Documentation ....................................................................................... 62
2.14
I2S Audio ..................................................................... 65
2.14.1
API Cross Reference ............................................................................................. 65
2.14.2
Enumeration Type Documentation ........................................................................ 65
2.14.3
Function Documentation ....................................................................................... 68
2.15
SPI Bus ........................................................................ 72
2.15.1
API Cross Reference ............................................................................................. 72
2.15.2
Enumeration Type Documentation ........................................................................ 72
2.15.3
Function Documentation ....................................................................................... 74
2
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.16
C learance N o.: FT DI#453
CANBus........................................................................ 80
2.16.1
API Cross Reference ............................................................................................. 80
2.16.2
Enumeration Type Documentation ........................................................................ 80
2.16.3
Function Documentation ....................................................................................... 83
2.16.4
Variable Documentation ....................................................................................... 89
2.17
Camera interface .......................................................... 90
2.17.1
API Cross Reference ............................................................................................. 90
2.17.2
Enumeration Type Documentation ........................................................................ 90
2.17.3
Function Documentation ....................................................................................... 90
2.18
Pulse Width Modulation ................................................ 93
2.18.1
API Cross Reference ............................................................................................. 93
2.18.2
Enumeration Type Documentation ........................................................................ 93
2.18.3
Function Documentation ....................................................................................... 93
2.19
PWM Audio .................................................................. 97
2.19.1
API Cross Reference ............................................................................................. 97
2.19.2
Enumeration Type Documentation ........................................................................ 97
2.19.3
Function Documentation ....................................................................................... 99
2.20
Real Time Clock .......................................................... 102
2.20.1
API Cross Reference ........................................................................................... 102
2.20.2
Enumeration Type Documentation ...................................................................... 102
2.20.3
Function Documentation ..................................................................................... 102
2.21
USB Device Stack API ................................................. 105
2.21.1
API Cross Reference ........................................................................................... 105
2.21.2
Macro Definition Documentation ......................................................................... 105
2.21.3
Typedef Documentation...................................................................................... 106
2.21.4
Enumeration Type Documentation ...................................................................... 107
2.21.5
Structure Documentation.................................................................................... 109
2.21.6
Function Documentation ..................................................................................... 110
2.22
DFU Device for USB Device Stack API .......................... 118
2.22.1
API Cross Reference ........................................................................................... 118
2.22.2
Macro Definition Documentation ......................................................................... 118
2.22.3
Function Documentation ..................................................................................... 119
2.23
2.23.1
USB Host Stack API .................................................... 122
API Cross Reference ........................................................................................... 122
3
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.23.2
Macro Definition Documentation ......................................................................... 122
2.23.3
Typedef Documentation...................................................................................... 123
2.23.4
Structure Documentation.................................................................................... 124
2.23.5
Enumeration Type Documentation ...................................................................... 126
2.23.6
Function Documentation ..................................................................................... 128
2.24
USB Host Stack Extensions API ................................... 143
2.24.1
API Cross Reference ........................................................................................... 143
2.24.2
Function Documentation ..................................................................................... 143
2.25
HID Devices on USB Host Stack API ............................ 146
2.25.1
API Cross Reference ........................................................................................... 146
2.25.2
Structure Documentation.................................................................................... 146
2.25.3
Function Documentation ..................................................................................... 147
2.26
BOMS Devices on USB Host Stack API ......................... 150
2.26.1
API Cross Reference ........................................................................................... 150
2.26.2
Macro Definition Documentation ......................................................................... 150
2.26.3
Structure Documentation.................................................................................... 151
2.26.4
Function Documentation ..................................................................................... 152
2.27
CDC ACM Devices on USB Host Stack API .................... 157
2.27.1
Macro Definition Documentation ......................................................................... 157
2.27.2
Structure Documentation.................................................................................... 159
2.27.3
Function Documentation ..................................................................................... 161
2.28
API
Android Open Accessory (AOA) Devices on USB Host Stack
169
2.28.1
API Cross Reference ........................................................................................... 169
2.28.2
Macro Definition Documentation ......................................................................... 169
2.28.3
Structure Documentation.................................................................................... 170
2.28.4
Function Documentation ..................................................................................... 171
2.29
Startup DFU Feature ................................................... 175
2.29.1
API Cross Reference ........................................................................................... 175
2.29.2
Function Documentation ..................................................................................... 176
2.30
SD Host...................................................................... 177
2.30.1
Enumeration Type Documentation ...................................................................... 177
2.30.2
Function Documentation ..................................................................................... 178
2.31
Datalogger Feature .................................................... 179
4
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.31.1
Datalogger Partition ........................................................................................... 180
2.31.2
API Cross Reference ........................................................................................... 180
2.31.3
Variable Documentation ..................................................................................... 180
2.31.4
Function Documentation ..................................................................................... 181
2.32
D2XX Feature ............................................................. 182
2.32.1
API Cross Reference ........................................................................................... 182
2.32.2
Variable Documentation ..................................................................................... 183
2.32.3
Macro Definition Documentation ......................................................................... 183
2.32.4
Structure Documentation.................................................................................... 183
2.32.5
Enumeration Type Documentation ...................................................................... 184
2.32.6
Typedef Documentation...................................................................................... 185
2.32.7
Function Documentation ..................................................................................... 186
3 Header Files ........................................................ 189
3.1 Hardware Register Definition Files ................................ 189
3.1.1
Using Register Header Files ................................................................................ 189
3.2 API Header Files ........................................................... 191
3.3 Additional Header Files ................................................. 192
4 Contact Information ............................................ 193
Appendix A – References ......................................... 194
Document References .......................................................... 194
Acronyms and Abbreviations ................................................ 194
Appendix B – List of Tables & Figures ....................... 196
List of Tables ....................................................................... 196
List of Figures ...................................................................... 196
Appendix C – Revision History .................................. 197
5
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
1 Introduction
The FT900 Peripheral Driver Library is a collection of ‘C’ language based functions that are
intended to ease the development of applications running on the FT900 Microcontroller.
Figure 1-1 shows the overall FT90X Interface driver support. This document focuses on the
Hardware Interface Driver layer. All drivers will be provided as source code for easy adaptation
and modification.
Figure 1-1 FT90x Interface Driver Support
1.1 Overview
This document will describe API for the FT900 Peripheral Driver Library.
6
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2 libft900.a Library
The precompiled driver library can be used as is. However, if you want to change the way any of
the source code in the libFT900 library works then copying the source code of a module to the
Eclipse project you are working on allows you to ignore the version in the library and try out local
changes.
For example, if you want to change the timeout on the STARTUP_DFU() code from 500ms to 10
seconds then copy the source code usb_startup_dfu.c to the project and make the changes
required in the project’s workspace.
Compiling against the library will take the local version in preference to the library’s version.
Source code can be found here (once IDE has been installed):
C:\Program Files (x86)\FTDI\FT90x Toolchain\Toolchain\hardware\src
2.1 Chip management
The file ft900_sys.h contains the definitions for the chip management functions in the libft900.a
library.
2.1.1
API Cross Reference
It utilises the following library APIs:
ft900_delay.h – Delay
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.1.2
Enumeration Type Documentation
2.1.2.1 sys_dev ice_t
enum sys_device_t
FT900 Device.
Enumerator
sys_device_usb_host
USB Host
sys_device_usb_device
USB Device
sys_device_ethernet
Ethernet
sys_device_sd_card
SD Card
sys_device_can0
CAN0
sys_device_can1
CAN1
sys_device_i2c_master
I2C Master
sys_device_i2c_slave
I2C Slave
7
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
sys_device_spi_master
SPI Master
sys_device_spi_slave0
SPI Slave 0
sys_device_spi_slave1
SPI Slave 1
sys_device_uart0
UART0
sys_device_uart1
UART1
sys_device_pwm
PWM
sys_device_i2s
I2S
sys_device_camera
Camera
sys_device_timer_wdt
Timer and Watchdog Timer
sys_device_adc
Analogue to Digital Converter
sys_device_dac0
Digital to Analogue Converter 0
sys_device_dac1
Digital to Analogue Converter 1
C learance N o.: FT DI#453
2.1.2.2 sys_cpu_div ider_t
enum sys_cpu_divider_t
CPU Clock divider.
Enumerator
sys_cpu_divider_1
No clock divider (Default)
sys_cpu_divider_2
Divide Input Clock by 2
sys_cpu_divider_4
Divide Input Clock by 4
sys_cpu_divider_8
Divide Input Clock by 8
sys_cpu_divider_64
Divide Input Clock by 64
sys_cpu_divider_128
Divide Input Clock by 128
sys_cpu_divider_512
Divide Input Clock by 512
2.1.2.3 sys_pwm _trigger_t
enum sys_pwm_trigger_t
PWM External Trigger pin.
Enumerator
sys_pwm_trigger_none
None
8
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
sys_pwm_trigger_gpio18
GPIO18
sys_pwm_trigger_gpio26
GPIO26
sys_pwm_trigger_gpio35
GPIO35
sys_pwm_trigger_gpio40
GPIO40
sys_pwm_trigger_gpio46
GPIO46
sys_pwm_trigger_gpio52
GPIO52
sys_pwm_trigger_gpio58
GPIO58
2.1.3
C learance N o.: FT DI#453
Function Documentation
2.1.3.1 sys_enable
int sys_enable ( sys_device_t
dev )
Enable a device on the FT900.
Parameters
dev The device to enable
Returns
On success a 0, otherwise -1
2.1.3.2 sys_disable
int sys_disable ( sys_device_t
dev )
Disable a device on the FT900.
Parameters
dev The device to Disable
Returns
On success a 0, otherwise -1
2.1.3.3 sys_reset_all
void sys_reset_all ( void
)
Reset all peripherals. sys_cpu_clock_div
int sys_cpu_clock_div ( sys_cpu_divider_t
div )
Enable a divider on the CPU.
Parameters
div The divider to use
Returns
On success a 0, otherwise -1
9
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.1.3.4 sys_get_cpu_clock
uint32_t sys_get_cpu_clock ( void
)
Get the current clock of the CPU.
Returns
The clock rate of the CPU in Hertz
2.1.3.5 sys_i2c_swop
int sys_i2c_swop ( uint8_t swop )
Swap the I2C Master and slave pins. The user must first configure the default master pins and
assign the swapped I2C master to those pins. For example:
gpio_function(44, pad_i2c1_scl);
gpio_pull(44, pad_pull_none);
gpio_function(45, pad_i2c1_sda);
gpio_pull(45, pad_pull_none);
Parameters
swop Enable or disable the swop feature
Returns
On success a 0, otherwise -1
2.1.3.6 sys_pwm _ext_trigger
int sys_pwm_ext_trigger ( sys_pwm_trigger_t
exttrigger )
Configure the External PWM trigger.
Parameters
exttrigger The selection of external trigger
Returns
On success a 0, otherwise -1
10
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.2 Delay functions
The file ft900_delay.h contains the definitions for the delay functions in the libft900.a library.
2.2.1
API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.2.2
Macro Definition Documentation
2.2.2.1 sleep
#define sleep (
x)
delayms(x*1000)
POSIX standard second sleep call.
Parameters
x The number of milliseconds to sleep
2.2.2.2 usleep
#define usleep (
x)
delayus(x)
POSIX standard microsecond sleep call.
Parameters
x The number of microseconds to sleep
11
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.3 Interrupt Management
The file ft900_interrupt.h contains the definitions for the interrupt management functions in the
libft900.a library.
2.3.1
API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.3.2
Macro Definition Documentation
2.3.2.1 N_INTERRUPTS
#define N_INTERRUPTS
(33)
The number of interrupts supported by the CPU.
2.3.3
Typedef Documentation
2.3.3.1 isrptr_t
typedef void(* isrptr_t) (void)
Interrupt handler function prototype.
2.3.4
Enumeration Type Documentation
2.3.4.1 interrupt_t
enum interrupt_t
Interrupt vector.
Enumerator
interrupt_0
Reserved
interrupt_usb_host
USB Host Interrupt
interrupt_usb_device
USB Device Interrupt
interrupt_ethernet
Ethernet Interrupt
interrupt_sd_card
SD Card Interrupt
interrupt_can0
CAN0 Interrupt
interrupt_can1
CAN1 Interrupt
interrupt_camera
Camera Interrupt
interrupt_spim
SPI Master Interrupt
interrupt_spis0
SPI Slave 0 Interrupt
interrupt_spis1
SPI Slave 1 Interrupt
12
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
interrupt_i2cm
I2C Master Interrupt
interrupt_i2cs
I2C Slave Interrupt
interrupt_uart0
UART0 Interrupt
interrupt_uart1
UART1 Interrupt
interrupt_i2s
I2S Interrupt
interrupt_pwm
PWM Interrupt
interrupt_timers
Timers Interrupt
interrupt_gpio
GPIO Interrupt
interrupt_rtc
RTC Interrupt
interrupt_adc
ADC Interrupt
interrupt_dac
DAC Interrupt
C learance N o.: FT DI#453
interrupt_slowclock
2.3.5
Function Documentation
2.3.5.1 interrupt_attach
int8_t interrupt_attach ( interrupt_t interrupt,
uint8_t
priority,
isrptr_t
func
)
Attach an interrupt.
Parameters
interrupt The interrupt vector to attach to
priority
The priority to give the interrupt
func
The function to call when interrupted
Returns
0 on a success or -1 for a failure
2.3.5.2 interrupt_detach
int8_t interrupt_detach ( interrupt_t interrupt )
Detach an interrupt.
Parameters
interrupt The interrupt vector to detach
Returns
13
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
0 on a success or -1 for a failure
2.3.5.3 interrupt_disable_globally
int8_t interrupt_disable_globally ( void
)
Disable all interrupts.
Returns
0 on a success or -1 for a failure
2.3.5.4 interrupt_disable_nesting
int8_t interrupt_disable_nesting ( void
)
Disable nesting interrupts.
Returns
0 on a success or -1 for a failure
2.3.5.5 interrupt_enable_globally
int8_t interrupt_enable_globally ( void
)
Enable interrupts to fire.
Returns
0 on a success or -1 for a failure
2.3.5.6 interrupt_enable_nesting
int8_t interrupt_enable_nesting ( uint8_t max )
Enable nesting interrupts.
Parameters
max The maximum number of levels to nest (max 16)
Returns
0 on a success or -1 for a failure
14
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4 General Purpose I/O and Pad Control
The file ft900_gpio.h contains the definitions for the GPIO and Pad Control functions in the
libft900.a library.
2.4.1
API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.4.2
Function to Pad Mappings
Pin mappings are made from a function to one of four groups. The groups and hence the available
functions on a pin are shown in the following table.
Pin
pad_func_0
pad_func_1
pad_func_2
pad_func_3
VBUS_DISCH/GPIO0
GPIO0
OC_N/GPIO1
GPIO1
PSW_N/GPIO2
GPIO2
VBUS_DTC/GPIO3
GPIO3
VBUS_DTC
ENET_LED0/GPIO4
GPIO4
ENET_LED0
ENET_LED1/GPIO5
GPIO5
ENET_LED1
ADC1/CAM_XCLK/GPIO6
GPIO6
CAM_XCLK
ADC1
ADC2/CAM_PCLK/GPIO7
GPIO7
CAM_PCLK
ADC2
ADC3/CAM_VD/GPIO8
GPIO8
CAM_VD
ADC3
ADC4/CAM_HD/GPIO9
GPIO9
CAM_HD
ADC4
ADC5/CAM_D7/GPIO10
GPIO10
CAM_D7
ADC5
ADC6/CAM_D6/GPIO11
GPIO11
CAM_D6
ADC6
ADC7/CAM_D5/GPIO12
GPIO12
CAM_D5
ADC7
DAC1/CAM_D4/GPIO13
GPIO13
CAM_D4
DAC1
DAC0/CAM_D3/GPIO14
GPIO14
CAM_D3
DAC0
CAN0_TXD/CAM_D2/GPIO15
GPIO15
CAM_D2
CAN0_TXD
CAN0_RXD/CAM_D1/GPIO16
GPIO16
CAM_D1
CAN0_RXD
CAN1_TXD/CAM_D0/GPIO17
GPIO17
CAM_D0
CAN1_TXD
CAN1_RXD/GPIO18
GPIO18
SD_CLK/GPIO19
GPIO19
SD_CLK
SD_CMD/GPIO20
GPIO20
SD_CMD
OC_N
CAN1_RXD
15
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
SD_DATA3/GPIO21
GPIO21
SD_DATA3
SD_DATA2/GPIO22
GPIO22
SD_DATA2
SD_DATA1/GPIO23
GPIO23
SD_DATA1
SD_DATA0/GPIO24
GPIO24
SD_DATA0
SD_CD/GPIO25
GPIO25
SD_CD
SD_WP/GPIO26
GPIO26
SD_WP
SPIM_CLK/GPIO27
GPIO27
SPIM_CLK
SPIM_SS0/GPIO28
GPIO28
SPIM_SS0
SPIM_MOSI/GPIO29
GPIO29
SPIM_MOSI
SPIM_MISO/GPIO30
GPIO30
SPIM_MISO
SPIM_IO2/GPIO31
GPIO31
SPIM_IO2
SPIM_IO3/GPIO32
GPIO32
SPIM_IO3
SPIM_SS1/GPIO33
GPIO33
SPIM_SS1
SPIM_SS2/GPIO34
GPIO34
SPIM_SS2
SPIM_SS3/GPIO35
GPIO35
SPIM_SS3
SPIS0_CLK/GPIO36
GPIO36
SPIS0_CLK
SPIS0_SS/GPIO37
GPIO37
SPIS0_SS
SPIS0_MOSI/GPIO38
GPIO38
SPIS0_MOSI
SPIS0_MISO/GPIO39
GPIO39
SPIS0_MISO
SPIS1_CLK/GPIO40
GPIO40
SPIS1_CLK
SPIS1_SS/GPIO41
GPIO41
SPIS1_SS
SPIS1_MOSI/GPIO42
GPIO42
SPIS1_MOSI
SPIS1_MISO/GPIO43
GPIO43
SPIS1_MISO
I2C0_SCL/GPIO44
GPIO44
I2C0_SCL
I2C0_SDA/GPIO45
GPIO45
I2C0_SDA
I2C1_SCL/GPIO46
GPIO46
I2C1_SCL
I2C1_SDA/GPIO47
GPIO47
I2C1_SDA
UART0_TXD/GPIO48
GPIO48
UART0_TXD
UART0_RXD/GPIO49
GPIO49
UART0_RXD
UART0_RTS/GPIO50
GPIO50
UART0_RTS
UART0_CTS/GPIO51
GPIO51
UART0_CTS
16
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
UART0_DTR/UART1_TXD/PWM4/GPIO52
GPIO52
PWM4
UART1_TXD
UART0_DTR
UART0_DSR/UART1_RXD/PWM5/GPIO53
GPIO53
PWM5
UART1_RXD
UART0_DSR
UART0_DCD/UART1_RTS/PWM6/GPIO54
GPIO54
PWM6
UART1_RTS
UART0_DCD
UART0_RI/UART1_CTS/PWM7/GPIO55
GPIO55
PWM7
UART1_CTS
UART0_RI
PWM0/GPIO56
GPIO56
PWM0
PWM1/GPIO57
GPIO57
PWM1
PWM2/GPIO58
GPIO58
PWM2
PWM3/GPIO59
GPIO59
PWM3
I2S_SDAO/GPIO60
GPIO60
I2S_SDAO
I2S_SDAI/GPIO61
GPIO61
I2S_SDAI
I2S_BCLK/GPIO62
GPIO62
I2S_BCLK
I2SS_BCLK
I2S_LRCLK/GPIO63
GPIO63
I2S_LRCLK
I2SS_LRCLK
I2S_MCLK/GPIO64
GPIO64
I2S_MCLK
I2S_CLK22/GPIO65
GPIO65
I2S_CLK22
I2S_CLK24/GPIO66
GPIO66
I2S_CLK24
2.4.3
Enumeration Type Documentation
2.4.3.1 gpio_int_edge_t
enum gpio_int_edge_t
GPIO Interrupt control.
Enumerator
gpio_int_edge_falling
Interrupt on a falling edge
gpio_int_edge_raising
Interrupt on a raising edge
2.4.3.2 pad_dir_t
enum pad_dir_t
Pad direction control.
Enumerator
pad_dir_input
Input
pad_dir_output
Output
pad_dir_open_drain
Open Drain
17
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4.3.3 pad_driv e_t
enum pad_drive_t
Pad current drive control.
Enumerator
pad_drive_4mA
4mA maximum current
pad_drive_8mA
8mA maximum current
pad_drive_12mA
12mA maximum current
pad_drive_16mA
16mA maximum current
2.4.3.4 pad_func_t
enum pad_func_t
Pad function control.
Enumerator
pad_func_0
Pad function 0
pad_func_1
Pad function 1
pad_func_2
Pad function 2
pad_func_3
Pad function 3
pad_gpio0
VBUS_DISCH/GPIO0 Pad function 0
pad_gpio1
OC_N/GPIO1 Pad function 0
pad_gpio2
PSW_N/GPIO2 Pad function 0
pad_gpio3
VBUS_DTC/GPIO3 Pad function 0
pad_gpio4
ENET_LED0/GPIO4 Pad function 0
pad_gpio5
ENET_LED1/GPIO5 Pad function 0
pad_gpio6
ADC1/CAM_XCLK/GPIO6 Pad function 0
pad_gpio7
ADC2/CAM_PCLK/GPIO7 Pad function 0
pad_gpio8
ADC3/CAM_VD/GPIO8 Pad function 0
pad_gpio9
ADC4/CAM_HD/GPIO9 Pad function 0
pad_gpio10
ADC5/CAM_D7/GPIO10 Pad function 0
pad_gpio11
ADC6/CAM_D6/GPIO11 Pad function 0
pad_gpio12
ADC7/CAM_D5/GPIO12 Pad function 0
18
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pad_gpio13
DAC1/CAM_D4/GPIO13 Pad function 0
pad_gpio14
DAC0/CAM_D3/GPIO14 Pad function 0
pad_gpio15
CAN0_TXD/CAM_D2/GPIO15 Pad function 0
pad_gpio16
CAN0_RXD/CAM_D1/GPIO16 Pad function 0
pad_gpio17
CAN1_TXD/CAM_D0/GPIO17 Pad function 0
pad_gpio18
CAN1_RXD/GPIO18 Pad function 0
pad_gpio19
SD_CLK/GPIO19 Pad function 0
pad_gpio20
SD_CMD/GPIO20 Pad function 0
pad_gpio21
SD_DATA3/GPIO21 Pad function 0
pad_gpio22
SD_DATA2/GPIO22 Pad function 0
pad_gpio23
SD_DATA1/GPIO23 Pad function 0
pad_gpio24
SD_DATA0/GPIO24 Pad function 0
pad_gpio25
SD_CD/GPIO25 Pad function 0
pad_gpio26
SD_WP/GPIO26 Pad function 0
pad_gpio27
SPIM_CLK/GPIO27 Pad function 0
pad_gpio28
SPIM_SS0/GPIO28 Pad function 0
pad_gpio29
SPIM_MOSI/GPIO29 Pad function 0
pad_gpio30
SPIM_MISO/GPIO30 Pad function 0
pad_gpio31
SPIM_IO2/GPIO31 Pad function 0
pad_gpio32
SPIM_IO3/GPIO32 Pad function 0
pad_gpio33
SPIM_SS1/GPIO33 Pad function 0
pad_gpio34
SPIM_SS2/GPIO34 Pad function 0
pad_gpio35
SPIM_SS3/GPIO35 Pad function 0
pad_gpio36
SPIS0_CLK/GPIO36 Pad function 0
pad_gpio37
SPIS0_SS/GPIO37 Pad function 0
pad_gpio38
SPIS0_MOSI/GPIO38 Pad function 0
pad_gpio39
SPIS0_MISO/GPIO39 Pad function 0
pad_gpio40
SPIS1_CLK/GPIO40 Pad function 0
pad_gpio41
SPIS1_SS/GPIO41 Pad function 0
C learance N o.: FT DI#453
19
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pad_gpio42
SPIS1_MOSI/GPIO42 Pad function 0
pad_gpio43
SPIS1_MISO/GPIO43 Pad function 0
pad_gpio44
I2C0_SCL/GPIO44 Pad function 0
pad_gpio45
I2C0_SDA/GPIO45 Pad function 0
pad_gpio46
I2C1_SCL/GPIO46 Pad function 0
pad_gpio47
I2C1_SDA/GPIO47 Pad function 0
pad_gpio48
UART0_TXD/GPIO48 Pad function 0
pad_gpio49
UART0_RXD/GPIO49 Pad function 0
pad_gpio50
UART0_RTS/GPIO50 Pad function 0
pad_gpio51
UART0_CTS/GPIO51 Pad function 0
pad_gpio52
UART0_DTR/UART1_TXD/PWM4/GPIO52 Pad function 0
pad_gpio53
UART0_DSR/UART1_RXD/PWM5/GPIO53 Pad function 0
pad_gpio54
UART0_DCD/UART1_RTS/PWM6/GPIO54 Pad function 0
pad_gpio55
UART0_RI/UART1_CTS/PWM7/GPIO55 Pad function 0
pad_gpio56
PWM0/GPIO56 Pad function 0
pad_gpio57
PWM1/GPIO57 Pad function 0
pad_gpio58
PWM2/GPIO58 Pad function 0
pad_gpio59
PWM3/GPIO59 Pad function 0
pad_gpio60
I2S_SDAO/GPIO60 Pad function 0
pad_gpio61
I2S_SDAI/GPIO61 Pad function 0
pad_gpio62
I2S_BCLK/GPIO62 Pad function 0
pad_gpio63
I2S_LRCLK/GPIO63 Pad function 0
pad_gpio64
I2S_MCLK/GPIO64 Pad function 0
pad_gpio65
I2S_CLK22/GPIO65 Pad function 0
pad_gpio66
I2S_CLK24/GPIO66 Pad function 0
pad_oc_n
OC_N/GPIO1 Pad function 1
pad_vbus_dtc
VBUS_DTC/GPIO3 Pad function 1
pad_enet_led0
ENET_LED0/GPIO4 Pad function 1
pad_enet_led1
ENET_LED1/GPIO5 Pad function 1
C learance N o.: FT DI#453
20
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pad_cam_xclk
ADC1/CAM_XCLK/GPIO6 Pad function 1
pad_cam_pclk
ADC2/CAM_PCLK/GPIO7 Pad function 1
pad_cam_vd
ADC3/CAM_VD/GPIO8 Pad function 1
pad_cam_hd
ADC4/CAM_HD/GPIO9 Pad function 1
pad_cam_d7
ADC5/CAM_D7/GPIO10 Pad function 1
pad_cam_d6
ADC6/CAM_D6/GPIO11 Pad function 1
pad_cam_d5
ADC7/CAM_D5/GPIO12 Pad function 1
pad_cam_d4
DAC1/CAM_D4/GPIO13 Pad function 1
pad_cam_d3
DAC0/CAM_D3/GPIO14 Pad function 1
pad_cam_d2
CAN0_TXD/CAM_D2/GPIO15 Pad function 1
pad_cam_d1
CAN0_RXD/CAM_D1/GPIO16 Pad function 1
pad_cam_d0
CAN1_TXD/CAM_D0/GPIO17 Pad function 1
pad_sd_clk
SD_CLK/GPIO19 Pad function 1
pad_sd_cmd
SD_CMD/GPIO20 Pad function 1
pad_sd_data3
SD_DATA3/GPIO21 Pad function 1
pad_sd_data2
SD_DATA2/GPIO22 Pad function 1
pad_sd_data1
SD_DATA1/GPIO23 Pad function 1
pad_sd_data0
SD_DATA0/GPIO24 Pad function 1
pad_sd_cd
SD_CD/GPIO25 Pad function 1
pad_sd_wp
SD_WP/GPIO26 Pad function 1
pad_spim_sck
SPIM_CLK/GPIO27 Pad function 1
pad_spim_ss0
SPIM_SS0/GPIO28 Pad function 1
pad_spim_mosi
SPIM_MOSI/GPIO29 Pad function 1
pad_spim_miso
SPIM_MISO/GPIO30 Pad function 1
pad_spim_io2
SPIM_IO2/GPIO31 Pad function 1
pad_spim_io3
SPIM_IO3/GPIO32 Pad function 1
pad_spim_ss1
SPIM_SS1/GPIO33 Pad function 1
pad_spim_ss2
SPIM_SS2/GPIO34 Pad function 1
pad_spim_ss3
SPIM_SS3/GPIO35 Pad function 1
C learance N o.: FT DI#453
21
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pad_spis0_clk
SPIS0_CLK/GPIO36 Pad function 1
pad_spis0_ss
SPIS0_SS/GPIO37 Pad function 1
pad_spis0_mosi
SPIS0_MOSI/GPIO38 Pad function 1
pad_spis0_miso
SPIS0_MISO/GPIO39 Pad function 1
pad_spis1_clk
SPIS1_CLK/GPIO40 Pad function 1
pad_spis1_ss
SPIS1_SS/GPIO41 Pad function 1
pad_spis1_mosi
SPIS1_MOSI/GPIO42 Pad function 1
pad_spis1_miso
SPIS1_MISO/GPIO43 Pad function 1
pad_i2c0_scl
I2C0_SCL/GPIO44 Pad function 1
pad_i2c0_sda
I2C0_SDA/GPIO45 Pad function 1
pad_i2c1_scl
I2C1_SCL/GPIO46 Pad function 1
pad_i2c1_sda
I2C1_SDA/GPIO47 Pad function 1
pad_pwm4
UART0_DTR/UART1_TXD/PWM4/GPIO52 Pad function 1
pad_pwm5
UART0_DSR/UART1_RXD/PWM5/GPIO53 Pad function 1
pad_pwm6
UART0_DCD/UART1_RTS/PWM6/GPIO54 Pad function 1
pad_pwm7
UART0_RI/UART1_CTS/PWM7/GPIO55 Pad function 1
pad_pwm0
PWM0/GPIO56 Pad function 1
pad_pwm1
PWM1/GPIO57 Pad function 1
pad_pwm2
PWM2/GPIO58 Pad function 1
pad_pwm3
PWM3/GPIO59 Pad function 1
pad_i2s_sdao
I2S_SDAO/GPIO60 Pad function 1
pad_i2s_sdai
I2S_SDAI/GPIO61 Pad function 1
pad_i2s_bclk
I2S_BCLK/GPIO62 Pad function 1
pad_i2s_lrclk
I2S_LRCLK/GPIO63 Pad function 1
pad_i2s_mclk
I2S_MCLK/GPIO64 Pad function 1
pad_i2s_clk22
I2S_CLK22/GPIO65 Pad function 1
pad_i2s_clk24
I2S_CLK24/GPIO66 Pad function 1
pad_can0_txd
CAN0_TXD/CAM_D2/GPIO15 Pad function 2
pad_can0_rxd
CAN0_RXD/CAM_D1/GPIO16 Pad function 2
C learance N o.: FT DI#453
22
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pad_can1_txd
CAN1_TXD/CAM_D0/GPIO17 Pad function 2
pad_can1_rxd
CAN1_RXD/GPIO18 Pad function 2
pad_uart1_txd
UART0_DTR/UART1_TXD/PWM4/GPIO52 Pad function 2
pad_uart1_rxd
UART0_DSR/UART1_RXD/PWM5/GPIO53 Pad function 2
pad_uart1_rts
UART0_DCD/UART1_RTS/PWM6/GPIO54 Pad function 2
pad_uart1_cts
UART0_RI/UART1_CTS/PWM7/GPIO55 Pad function 2
pad_i2ss_bclk
I2S_BCLK/GPIO62 Pad function 2
pad_i2ss_lrclk
I2S_LRCLK/GPIO63 Pad function 2
pad_adc1
ADC1/CAM_XCLK/GPIO6 Pad function 3
pad_adc2
ADC2/CAM_PCLK/GPIO7 Pad function 3
pad_adc3
ADC3/CAM_VD/GPIO8 Pad function 3
pad_adc4
ADC4/CAM_HD/GPIO9 Pad function 3
pad_adc5
ADC5/CAM_D7/GPIO10 Pad function 3
pad_adc6
ADC6/CAM_D6/GPIO11 Pad function 3
pad_adc7
ADC7/CAM_D5/GPIO12 Pad function 3
pad_dac1
DAC1/CAM_D4/GPIO13 Pad function 3
pad_dac0
DAC0/CAM_D3/GPIO14 Pad function 3
pad_uart0_txd
UART0_TXD/GPIO48 Pad function 3
pad_uart0_rxd
UART0_RXD/GPIO49 Pad function 3
pad_uart0_rts
UART0_RTS/GPIO50 Pad function 3
pad_uart0_cts
UART0_CTS/GPIO51 Pad function 3
pad_uart0_dtr
UART0_DTR/UART1_TXD/PWM4/GPIO52 Pad function 3
pad_uart0_dsr
UART0_DSR/UART1_RXD/PWM5/GPIO53 Pad function 3
pad_uart0_dcd
UART0_DCD/UART1_RTS/PWM6/GPIO54 Pad function 3
pad_uart0_ri
UART0_RI/UART1_CTS/PWM7/GPIO55 Pad function 3
C learance N o.: FT DI#453
23
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4.3.5 pad_pull_t
enum pad_pull_t
Pad pull up and pull downs control.
Enumerator
pad_pull_none
No pull up or pull down
pad_pull_pullup
Weak pull up enabled
pad_pull_pulldown
Weak pull down enabled
pad_pull_keeper
Weak pull up/down reflects output
2.4.3.6 pad_schm itt_t
enum pad_schmitt_t
Pad Schmitt trigger control.
Enumerator
pad_schmitt_off
Pad input is filtered through a schmitt trigger
pad_schmitt_on
Pad input is unfiltered
2.4.3.7 pad_slew_t
enum pad_slew_t
Pad slew rate control.
Enumerator
pad_slew_fast
Fast Slew Rate
pad_slew_slow
Slow Slew Rate
2.4.4
Function Documentation
2.4.4.1 gpio_dir
int8_t gpio_dir ( uint8_t
num,
pad_dir_t dir
)
Configure the direction of a pin.
Parameters
num The GPIO number
dir
The direction
24
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
On success a 0, otherwise -1
2.4.4.2 gpio_function
int8_t gpio_function ( uint8_t
num,
pad_func_t
func
)
Configure the alternative function for a pin.
Parameters
num The GPIO number
func The function that the pin should use
Returns
On success a 0, otherwise -1
2.4.4.3 gpio_idriv e
int8_t gpio_idrive ( uint8_t
num,
pad_drive_t drive
)
Configure the maximum current drive for a pin.
Parameters
num The GPIO number
drive The maximum current
Returns
On success a 0, otherwise -1
2.4.4.4 gpio_pull
int8_t gpio_pull ( uint8_t
num,
pad_pull_t pull
)
Configure the pull up/down for a pin.
Parameters
num The GPIO number
pull The pullup/down configuration
Returns
On success a 0, otherwise -1
25
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4.4.5 gpio_schm itt
int8_t gpio_schmitt ( uint8_t
num,
pad_schmitt_t schmitt
)
Configure the schmitt trigger for a pin.
Parameters
num
The GPIO number
schmitt The Schmitt trigger configuration
Returns
On success a 0, otherwise -1
2.4.4.6 gpio_slew
int8_t gpio_slew ( uint8_t
num,
pad_slew_t slew
)
Configure the slew rate for a pin.
Parameters
num The GPIO number
slew The slew rate of the pin
Returns
On success a 0, otherw ise -1
2.4.4.7 gpio_read
int8_t gpio_read ( uint8_t num )
Read a value from a GPIO pin.
Parameters
num The GPIO number
Returns
The value of the pin (1 = high, 0 = low), otherwise -1
26
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4.4.8 gpio_write
int8_t gpio_write ( uint8_t num,
uint8_t val
)
Write a value to a GPIO pin.
Parameters
num The GPIO number
val
The value to write
Returns
On success a 0, otherwise -1
2.4.4.9 gpio_toggle
int8_t gpio_toggle ( uint8_t
num )
Toggle the value of a GPIO pin.
Parameters
num The GPIO number
Returns
On success a 0, otherwise -1
2.4.4.10 gpio_interrupt_enable
int8_t gpio_interrupt_enable ( uint8_t
num,
gpio_int_edge_t
edge
)
Enable an interrupt on a GPIO pin.
Parameters
num The GPIO number
edge The edge at which to trigger on
Returns
On success a 0, otherwise -1
2.4.4.11 gpio_interrupt_disable
int8_t gpio_interrupt_disable ( uint8_t
num )
Disable an interrupt on a GPIO pin.
Parameters
num The GPIO number
Returns
On success a 0, otherwise -1
27
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.4.4.12 gpio_is_interrupted
int8_t gpio_is_interrupted ( uint8_t num )
Check if an interrupt has happened on a GPIO pin.
Parameters
num The GPIO number
Returns
On no interrupt 0, on an interrupt 1, otherwise -1
28
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.5 Assembler Definitions
The file ft900_asm.h contains the definitions for assembler instructions used in the libft900.a
library.
2.5.1
API Cross Reference
No additional definitions are required.
2.5.2
Macro Documentation
2.5.2.1 asm _noop
#define asm_noop()
A No Operation Instruction.
2.5.2.2 asm _m emcpy8
#define asm_memcpy8(src, dst, size)
8-bitwise memory copy.
Parameters
src A pointer to the source data.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.3 asm _m emcpy16
#define asm_memcpy16(src, dst, size)
16-bitwise memory copy.
Parameters
src A pointer to the source data.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.4 asm _m emcpy32
#define asm_memcpy32(src, dst, size)
32-bitwise memory copy.
Parameters
src A pointer to the source data.
dst A pointer to the destination data.
size The size of the data to copy.
29
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.5.2.5 asm _m emset8
#define asm_memset8(val, dst, size)
8-bitwise memory set.
Parameters
val The value to set the memory to.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.6 asm _m emset16
#define asm_memset16(val, dst, size)
16-bitwise memory set.
Parameters
val The value to set the memory to.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.7 asm _m emset32
#define asm_memset32(val, dst, size)
32-bitwise memory set.
Parameters
val The value to set the memory to.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.8 asm _strcpy
#define asm_strcpy(src, dst)
String copy.
Parameters
src A pointer to the source string.
dst A pointer to the destination string.
2.5.2.9 asm _stream in8
#define asm_streamin8 (src, dst, size)
8-bitwise memory stream from FIFO to memory.
Parameters
src A pointer to the source registers.
dst A pointer to the destination data.
30
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
size The size of the data to copy.
2.5.2.10 asm _ stream in16
#define asm_streamin16(src, dst, size)
16-bitwise memory stream from FIFO to memory.
Parameters
src A pointer to the source registers.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.11 asm _ stream in32
#define asm_streamin(src, dst, size)
32-bitwise memory stream from FIFO to memory.
Parameters
src A pointer to the source registers.
dst A pointer to the destination data.
size The size of the data to copy.
2.5.2.12 asm _stream out8
#define asm_streamout8 (src, dst, size)
8-bitwise memory stream from memory to FIFO.
Parameters
src A pointer to the source data.
dst A pointer to the destination registers.
size The size of the data to copy.
2.5.2.13 asm _ stream out16
#define asm_streamin16(src, dst, size)
16-bitwise memory stream from memory to FIFO.
Parameters
src A pointer to the source data.
dst A pointer to the destination registers.
size The size of the data to copy.
2.5.2.14 asm _ stream out32
#define asm_streamout(src, dst, size)
32-bitwise memory stream from memory to FIFO.
31
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
src A pointer to the source data.
dst A pointer to the destination registers.
size The size of the data to copy.
2.5.2.15 asm _setbit
#define asm_setbit(val, bit)
Set a bit in a 32 bit value.
Parameters
val The value to use.
bit The bit position to set.
2.5.2.16 asm _clrbit
#define asm_clrbit(val, bit)
Set a bit in a 32 bit value.
Parameters
val The value to use.
bit The bit position to clear.
2.5.2.17 asm _flip32
#define asm_flip32(src, dst, val)
Flip bit regions.
Parameters
src A pointer to the source data.
dst A pointer to the destination data.
val The region of bits to flip.
- If bit 0 is set, then every alternate bit is exchanged.
- If bit 1 is set, then every alternate 2-bit group is exchanged.
- If bit 2 is set, then every alternate 4-bit group is exchanged.
- If bit 3 is set, then every alternate 8-bit group is exchanged.
- If bit 4 is set, then the two 16-bit groups are exchanged.
2.5.2.18 asm _rev erse_endianness
#define asm_reverse_endianness (val)
Reverse the endianness of a value.
Parameters
val The value to use.
32
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.5.2.19 asm _rev erse_bits
#define asm_reverse_bits (val)
Reverse the bits of a value.
Parameters
val The value to use.
2.5.2.20 asm _rotate32
#define asm_rotate32 (val, num)
Rotate bits left or right.
Parameters
val
The value to use.
num The number and direction to rotate in (negative numbers rotate left).
2.5.3
Function Documentation
2.5.3.1 asm _strcm p
static inline int32_t asm_strcmp(const char *src1, const char *src2)
String compare.
Parameters
src1 A pointer to the first source string.
src2 A pointer to the second source string.
Returns
The difference between the two strings.
2.5.3.2 asm _strlen
static inline int32_t asm_strlen(const char *src)
String length.
Parameters
src A pointer to the source string.
Returns
The length of the string.
33
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.6 Watchdog Timer
The file ft900_wdt.h contains the definitions for the watchdog timer functions in the libft900.a
library.
2.6.1
API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.6.2
Enumeration Type Documentation
2.6.2.1 wdt_counter_t
enum wdt_counter_t
Watchdog Timeouts.
Enumerator
wdt_counter_1_clocks
10 nsec @ 100 MHz
wdt_counter_2_clocks
20 nsec @ 100 MHz
wdt_counter_4_clocks
40 nsec @ 100 MHz
wdt_counter_8_clocks
80 nsec @ 100 MHz
wdt_counter_16_clocks
160 nsec @ 100 MHz
wdt_counter_32_clocks
320 nsec @ 100 MHz
wdt_counter_64_clocks
640 nsec @ 100 MHz
wdt_counter_128_clocks
1.28 usec @ 100 MHz
wdt_counter_256_clocks
2.56 usec @ 100 MHz
wdt_counter_512_clocks
5.12 usec @ 100 MHz
wdt_counter_1K_clocks
10.24 usec @ 100 MHz
wdt_counter_2K_clocks
20.48 usec @ 100 MHz
wdt_counter_4K_clocks
40.96 usec @ 100 MHz
wdt_counter_8K_clocks
81.92 usec @ 100 MHz
wdt_counter_16K_clocks
163.84 usec @ 100 MHz
wdt_counter_32K_clocks
327.68 usec @ 100 MHz
wdt_counter_64K_clocks
655.35 usec @ 100 MHz
wdt_counter_128K_clocks
~1.31 msec @ 100 MHz
wdt_counter_256K_clocks
~2.62 msec @ 100 MHz
34
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
wdt_counter_512K_clocks
~5.24 msec @ 100 MHz
wdt_counter_1M_clocks
~10.49 msec @ 100 MHz
wdt_counter_2M_clocks
~20.97 msec @ 100 MHz
wdt_counter_4M_clocks
~41.94 msec @ 100 MHz
wdt_counter_8M_clocks
~83.89 msec @ 100 MHz
wdt_counter_16M_clocks
~167.77 msec @ 100 MHz
wdt_counter_32M_clocks
~335.54 msec @ 100 MHz
wdt_counter_64M_clocks
~671.09 msec @ 100 MHz
wdt_counter_128M_clocks
~1.34 sec @ 100 MHz
wdt_counter_256M_clocks
~2.68 sec @ 100 MHz
wdt_counter_512M_clocks
~5.37 sec @ 100 MHz
wdt_counter_1G_clocks
~10.74 sec @ 100 MHz
wdt_counter_2G_clocks
~21.47 sec @ 100 MHz
2.6.3
C learance N o.: FT DI#453
Function Documentation
2.6.3.1 wdt_init
int8_t wdt_init ( wdt_counter_t timeout )
Initialise and start the Watchdog timer.
Parameters
timeout The timeout value of the Watchdog
Returns
0 on success, -1 otherwise
2.6.3.2 wdt_kick
int8_t wdt_kick ( void
)
Reset a running Watchdog Timer.
Returns
0 on success, -1 otherwise
35
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.7 Timers
The file ft900_timers.h contains the definitions for the timer management functions in the
libft900.a library.
2.7.1
API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.7.2
Enumeration Type Documentation
2.7.2.1 tim er_select_t
enum timer_select_t
Timer Select.
Enumerator
timer_select_a
Timer A
timer_select_b
Timer B
timer_select_c
Timer C
timer_select_d
Timer D
2.7.2.2 tim er_direction_t
enum timer_direction_t
Timer count direction.
Enumerator
timer_direction_up
Count up
timer_direction_down
Count down
2.7.2.3 tim er_m ode_t
enum timer_mode_t
Timer count mode.
Enumerator
timer_mode_continuous
Count continuous
timer_mode_oneshot
Count one shot
2.7.2.4 tim er_prescaler_select_t
enum timer_prescaler_select_t
Timer prescaler select.
36
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Enumerator
timer_prescaler_select_off
Timer prescaler off
timer_prescaler_select_on
Timer prescaler on
2.7.3
Function Documentation
2.7.3.1 tim er_init
int8_t timer_init ( timer_select_t
timer,
uint16_t
initial,
timer_direction_t
dir,
timer_prescaler_select_t
prescaler,
timer_mode_t
mode
)
Initialise a timer.
Parameters
timer
The timer to set up
initial
The initial value for the timer
dir
The direction that the timer should count in
prescaler Whether or not this timer should use the prescaler
mode
If the timer should be continuously counting or a one shot
Returns
On success a 0, otherwise -1
2.7.3.2 tim er_start
int8_t timer_start ( timer_select_t
timer )
Start a timer.
Parameters
timer The timer to start
Returns
On success a 0, otherwise -1
37
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.7.3.3 tim er_stop
int8_t timer_stop ( timer_select_t timer )
Stop a timer.
Parameters
timer The timer to stop
Returns
2.7.3.4 On success a 0, otherwise - 1tim er_read
int8_t timer_read ( timer_select_t timer,
uint16_t *
value
)
Read the value of a timer.
Parameters
timer The timer to read from
value A pointer to store the value
Returns
On success a 0, otherwise -1
2.7.3.5 tim er_prescaler
int8_t timer_prescaler ( uint16_t prescaler )
Set up the prescaler.
Parameters
prescaler The clock prescaler to apply to the timer
Returns
On success a 0, otherwise -1
Warning
This can only be used before starting timers
2.7.3.6 tim er_disable_interrupt
int8 t timer disable interrupt (timer_select_t)
Disable the interrupt for a timer.
Parameters
timer The timer to disable the interrupt for
Returns
On success a 0, otherwise -1
38
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.7.3.7 tim er_enable_interrupt
int8_t timer_enable_interrupt ( timer_select_t
timer )
Enable the interrupt for a timer.
Parameters
timer The timer to enable the interrupt for
Returns
On success a 0, otherwise -1
2.7.3.8 tim er_is_interrupted
int8_t timer_is_interrupted ( timer_select_t timer )
Check if a timer has been interrupted.
Parameters
timer The timer to check
Warning
This function clears the current interrupt status bit
Returns
1 for if a timer is interrupted, 0 if the timer is not interrupted, -1 otherwise
39
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.8 Analogue to Digital Converter
The file ft900_adc.h contains the definitions for the analogue to digital conversion functions in the
libft900.a library.
2.8.1
API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.8.2
Enumeration Type Documentation
2.8.2.1 adc_m ode_t
enum adc_mode_t
ADC Run Mode.
Enumerator
adc_mode_single
One analogue reading will be taken and then the ADC stopped
adc_mode_continuous
The ADC will continuously acquire analogue readings
2.8.3
Function Documentation
2.8.3.1 adc_start
int8_t adc_start ( uint8_t channel )
Start the ADC capturing.
Parameters
channel The channel to select
Returns
0 on success, -1 otherwise
2.8.3.2 adc_stop
int8_t adc_stop ( void
)
Stop the ADC from capturing.
Returns
40
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.8.3.3 0 on success, - 1 otherwiseadc_m ode
int8 t adc mode (adc_mode_t mode)
Choose the mode that the ADC will run in.
Parameters
mode The mode (single or continuous)
Returns
0 on success, -1 otherwise
2.8.3.4 adc_read
int8_t adc_read ( uint16_t *
val )
Get the next sample from the ADC.
Parameters
val A pointer to store the sample
Returns
The number of samples read, -1 otherwise
2.8.3.5 adc_readn
int8_t adc_readn ( uint16_t * val,
size_t len
)
Get a collection of samples from the ADC.
Parameters
val An array pointer to store the samples
len The length of the array
Warning
This function will only work when the ADC is in continuous mode
Returns
The number of samples read, -1 otherwise
2.8.3.6 adc_available
uint8_t adc_available ( void
)
Get the number of ADC samples available.
Returns
The number of ADC samples
41
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.8.3.7 adc_disable_interrupt
int8_t adc_disable_interrupt ( void
)
Disable the Interrupt on the ADC.
Returns
0 on success, -1 otherwise
2.8.3.8 adc_enable_interrupt
int8_t adc_enable_interrupt ( void
)
Enable the Interrupt on the ADC.
Returns
0 on success, -1 otherwise
2.8.3.9 adc_is_interrupted
int8_t adc_is_interrupted ( void
)
Check that the ADC has been interrupted.
Warning
This function will clear the current interrupt bit when called
Returns
1 interrupted, 0 not interrupted
42
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.9 Digital to Analogue Converter
The file ft900_dac.h contains the definitions for the digital to analogue conversion functions in the
libft900.a library.
2.9.1
API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.9.2
Enumeration Type Documentation
2.9.2.1 dac_mode_t
enum dac_mode_t
DAC run mode.
Enumerator
dac_mode_single
Run the DAC in Single Shot mode
dac_mode_continuous
Run the DAC in Continuous mode
2.9.3
Function Documentation
2.9.3.1 dac_start
int8_t dac_start ( uint8_t num )
Start the DAC.
Parameters
num The DAC to use
Returns
0 on success, -1 otherwise
2.9.3.2 dac_stop
int8_t dac_stop ( uint8_t
num )
Stop the DAC.
Parameters
num The DAC to use
Returns
0 on success, -1 otherwise
43
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.9.3.3 dac_m ode
int8_t dac_mode ( uint8_t
dac_mode_t
num,
mode
)
Select the mode of the DAC.
Parameters
num The DAC to use
mode The mode the DAC should be in (single or continuous)
Returns
0 on success, -1 otherwise
2.9.3.4 dac_div ider
int8_t dac_divider ( uint8_t
div )
Select the divider for the DAC conversion rate.
fDAC=fperipheraldiv+1
Parameters
div The divider
Warning
The maximum conversion rate is 1 MHz
Returns
0 on success, -1 otherwise
2.9.3.5 dac_write
int8_t dac_write ( uint8_t
num,
uint16_t data
)
Write a value to the DAC.
This function will automatically update the DAC when it is in single mode.
Parameters
num The DAC to use
data The sample to write
Returns
The number of bytes written, -1 otherwise
44
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.9.3.6 dac_writen
int8_t dac_writen ( uint8_t
num,
uint16_t * data,
size_t
len
)
Write a series of values to the DAC.
Parameters
num The DAC to use
data The array of samples to write
len
The size of the array
Warning
This function will only work when continuous mode is selected
Returns
The number of bytes written, -1 otherwise
2.9.3.7 dac_available
uint8_t dac_available ( uint8_t num )
See how many samples are still being converted.
Parameters
num The DAC to use
Returns
The number of samples still to be converted, or 0 otherwise
2.9.3.8 dac_disable_interrupt
int8_t dac_disable_interrupt ( uint8_t
num )
Disable the interrupt on a DAC.
Parameters
num The DAC to use
Returns
0 on success, -1 otherwise
45
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.9.3.9 dac_enable_interrupt
int8_t dac_enable_interrupt ( uint8_t num )
Enable the interrupt on a DAC.
Enable the DAC module to generate an interrupt. The DAC module will generate an interrupt after
64 samples have been generated on the DAC.
Parameters
num The DAC to use
Returns
0 on success, -1 otherwise
2.9.3.10 dac_is_interrupted
int8_t dac_is_interrupted ( uint8_t
num )
Check if the DAC has fired an interrupt.
Parameters
num The DAC to use
Warning
This function clears the current interrupt status bit
Returns
1 when interrupted, 0 when not interrupted, -1 otherwise
46
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.10 Ethernet driver
The file ft900_eth.h contains the definitions for the Ethernet management and control functions
in the libft900.a library.
2.10.1 API Cross Reference
It utilises the following library APIs:
ft900_sys.h – Chip Management
ft900_gpio.h – General Purpose I/O and Pad Control
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.10.2 Enumeration Type Documentation
2.10.2.1 ethernet_led_mode_t
enum ethernet_led_mode_t
Ethernet LED pin mode.
Enumerator
ethernet_led_mode_link
Link active
ethernet_led_mode_tx
Transmit
ethernet_led_mode_rx
Receive
ethernet_led_mode_col
Collision
ethernet_led_mode_fdx
Full duplex
ethernet_led_mode_spd
Speed 10/100
2.10.3 Function Documentation
2.10.3.1 ethernet_init
void ethernet_init ( const uint8_t * mac )
Initialise the ethernet hardware.
Parameters
mac pointer to a six byte array containing MAC
2.10.3.2 ethernet_tx_enable
void ethernet_tx_enable ( int flag )
Enable or disable the Ethernet transmitter.
Parameters
flag 0 - disable transmitter, 1 - enable transmitter
47
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.10.3.3 ethernet_rx_enable
void ethernet_rx_enable ( int flag )
Enable or disable the Ethernet receiver.
Parameters
flag 0 - disable receiver, 1 - enable receiver
2.10.3.4 ethernet_led_m ode
void ethernet_led_mode ( uint8_t
led,
ethernet_led_mode_t mode
)
Set the mode of the led.
Parameters
led
The number of the led (0 or 1)
mode The mode which the led will be in
2.10.3.5 ethernet_set_m ac
void ethernet_set_mac ( const uint8_t *
mac )
Set the Ethernet MAC.
Parameters
mac A pointer to a six byte array containing MAC
2.10.3.6 ethernet_set_prom iscuous
void ethernet_set_promiscuous ( int flag )
Set the Ethernet peripheral in promiscuous mode.
Parameters
flag 0 - reset promiscuous mode, 1 - set promiscuous mode
2.10.3.7 ethernet_read
int ethernet_read ( size_t *
blen,
uint8_t * buf
)
Poll the ethernet peripheral for the reception of a single packet.
Parameters
buf Pointer to buffer to store the received packet.
blen Size of reception buffer
Returns
1 packet received, 0 no packet received
48
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.10.3.8 ethernet_m ii_read
uint16_t ethernet_mii_read ( uint8_t reg )
Read the content of an MII register.
Parameters
reg register to read
Returns
The content of requested register
2.10.3.9 ethernet_write
int ethernet_write ( uint8_t * buf,
size_t
blen
)
Outputs a packet on the ethernet interface.
The buffer must be in the following format: To send (n) bytes
Offset
Use
buf[0]
lsb of payload length (n & 0xff)
buf[1]
msb of payload length (n >> 16)
buf[2]
destination MAC[0]
buf[3]
destination MAC[1]
buf[4]
destination MAC[2]
buf[5]
destination MAC[3]
buf[6]
destination MAC[4]
buf[7]
destination MAC[5]
buf[8]
source MAC[0]
buf[9]
source MAC[1]
buf[10]
source MAC[2]
buf[11]
source MAC[3]
buf[12]
source MAC[4]
buf[13]
source MAC[5]
buf[14]
packet type
buf[15]
packet type
buf[16]
payload
buf[.]
...
49
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
buf[n+16]
C learance N o.: FT DI#453
end of payload (n bytes).
Parameters
buf Pointer to packet to send
blen Length of packet to send (in bytes)
2.10.3.10
ethernet_m ii_write
int ethernet_mii_write ( uint8_t
reg,
uint16_t v
)
Write a value to an MII register.
Parameters
reg Register to write to
v
Value to write to requested register
Returns
0 on success, -1 on error
2.10.3.11
ethernet_is_link_up
int ethernet_is_link_up ( void
)
Return the Ethernet link status.
Returns
1 - link up, 0 - link is not up.
2.10.3.12
ethernet_enable_interrupt
void ethernet_enable_interrupt ( uint8_t
mask )
Enable the Ethernet peripheral to fire interrupts.
Parameters
mask
50
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.11 UART
The file ft900_simple_uart.h contains the definitions for the UART management and contro l
functions in the libft900.a library.
2.11.1 API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.11.2 Macro Definition Documentation
#define UART_DIVIDER_1000000_BAUD
(25)
Predefined divider for 1000000 baud.
#define UART_DIVIDER_110_BAUD
(56818)
Predefined divider for 110 baud.
#define UART_DIVIDER_115200_BAUD
(217)
Predefined divider for 115200 baud.
#define UART_DIVIDER_1200_BAUD
(20833)
Predefined divider for 1200 baud.
#define UART_DIVIDER_150_BAUD
(55555)
Predefined divider for 150 baud.
#define UART_DIVIDER_19200_BAUD
(1302)
Predefined divider for 19200 baud.
#define UART_DIVIDER_230400_BAUD
(109)
Predefined divider for 230400 baud.
#define UART_DIVIDER_2400_BAUD
(10417)
Predefined divider for 2400 baud.
#define UART_DIVIDER_300_BAUD
(27778)
Predefined divider for 300 baud.
#define UART_DIVIDER_31250_BAUD
(800)
Predefined divider for 31250 baud.
#define UART_DIVIDER_38400_BAUD
(651)
Predefined divider for 38400 baud.
#define UART_DIVIDER_460800_BAUD
(54)
Predefined divider for 460800 baud.
#define UART_DIVIDER_4800_BAUD
(5208)
Predefined divider for 4800 baud.
51
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
#define UART_DIVIDER_57600_BAUD
C learance N o.: FT DI#453
(434)
Predefined divider for 57600 baud.
#define UART_DIVIDER_921600_BAUD
(27)
Predefined divider for 921600 baud.
#define UART_DIVIDER_9600_BAUD
(2604)
Predefined divider for 9600 baud.
2.11.3 Enumeration Type Documentation
2.11.3.1 uart_data_bits_t
enum uart_data_bits_t
UART Data bits.
Enumerator
uart_data_bits_5
5 data bits
uart_data_bits_6
6 data bits
uart_data_bits_7
7 data bits
uart_data_bits_8
8 data bits
2.11.3.2 uart_interrupt_t
enum uart_interrupt_t
UART Interrupts.
Enumerator
uart_interrupt_tx
Transmit Interrupt
uart_interrupt_rx
Receive Interrupt
uart_interrupt_dcd_ri_dsr_cts
DCD/RI/DSR/CTS Change Interrupt
2.11.3.3 uart_parity_t
enum uart_parity_t
UART Parity bits.
Enumerator
uart_parity_none
No parity
uart_parity_odd
Odd parity
uart_parity_even
Even parity
52
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.11.3.4 uart_stop_bits_t
enum uart_stop_bits_t
UART Stop bits.
Enumerator
uart_stop_bits_1
1 stop bit
uart_stop_bits_1_5
1.5 stop bit
uart_stop_bits_2
2 stop bit
2.11.4 Function Documentation
2.11.4.1 uart_open
int8_t uart_open ( ft900_uart_regs_t * dev,
uint8_t
prescaler,
uint32_t
divisor,
uart_data_bits_t
databits,
uart_parity_t
parity,
uart_stop_bits_t
stop
)
Open a UART for communication.
Parameters
dev
The device to use
prescaler The value of the prescaler
divisor
The value of the divisor
databits
The number of data bits
parity
The parity scheme
stop
The number of stop bits
Warning
1.5 stop bits is only available in 5 bit mode
Returns
0 on success, -1 otherwise
53
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.11.4.2 uart_close
int8_t uart_close ( ft900_uart_regs_t * dev )
Close a UART from communication.
Parameters
dev The device to use
Returns
0 on success, -1 otherwise
2.11.4.3 uart_calculate_baud
int32_t uart_calculate_baud ( uint32_t
target_baud,
uint8_t
samples,
uint32_t
f_perif,
uint16_t * divisor,
uint8_t *
prescaler
)
Calculate the prescaler and divisor from a baudrate.
Parameters
target_baud The baud rate to use
samples
The number of samples the UART will take for a bit, the default for this is 4
f_perif
Peripheral frequency, the default for this is 100,000,000
divisor
A pointer to store the divisor
prescaler
A pointer to store the prescaler, if this is NULL the prescaler will be set to 1
For Nsamples = 4 the following baud rates can be obtained from these Divisors and Prescalers:
Desired baud
Prescaler
Divisor
Actual baud
Error
110
4
56818
110.00035
~0.000%
150
3
55555
150.00150
+0.001%
300
3
27778
299.99760
~0.000%
1200
1
20833
1200.01920
+0.002%
2400
1
10417
2399.92320
-0.003%
4800
1
5208
4800.30720
+0.006%
9600
1
2604
9600.61440
+0.006%
19200
1
1302
19201.2288
+0.006%
31250
1
800
31250.00000
0.000%
38400
1
651
38402.45800
+0.006%
54
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
57600
1
434
57603.68700
+0.006%
115200
1
217
115207.37000
+0.006%
230400
1
109
229357.80000
-0.452%
460800
1
54
462962.96000
-0.469%
921600
1
27
925925.93000
-0.469%
1000000
1
25
1000000.00000
0.000%
C learance N o.: FT DI#453
Returns
The absolute error from the target baud rate
2.11.4.4 uart_puts
size_t uart_puts ( ft900_uart_regs_t * dev,
char *
str
)
Write a string to the serial port.
Parameters
dev The device to use
str The null-terminated string to write
Returns
The number of bytes written or -1 otherwise
2.11.4.5 uart_read
size_t uart_read ( ft900_uart_regs_t * dev,
uint8_t *
buffer
)
Read a data word from a UART.
Parameters
dev
The device to use
buffer A pointer to the data word to store into
Returns
The number of bytes read or -1 otherwise
55
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.11.4.6 uart_readn
size_t uart_readn ( ft900_uart_regs_t * dev,
uint8_t *
buffer,
size_t
len
)
Read a series of data words from a UART.
Parameters
dev
The device to use
buffer A pointer to the array of data words to store into
len
The number of data words to read
Returns
The number of bytes read or -1 otherwise
2.11.4.7 uart_write
size_t uart_write ( ft900_uart_regs_t * dev,
uint8_t
buffer
)
Write a data word to a UART.
Parameters
dev
The device to use
buffer The data to send
Returns
The number of bytes written or -1 otherwise
2.11.4.8 uart_writen
size_t uart_writen ( ft900_uart_regs_t * dev,
uint8_t *
buffer,
size_t
len
)
Write a series of data words to a UART.
Parameters
dev
The device to use
buffer A pointer to the array to send
len
The size of buffer
Returns
The number of bytes written or -1 otherwise
56
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.11.4.9 uart_is_interrupted
int8_t uart_is_interrupted ( ft900_uart_regs_t * dev,
uart_interrupt_t
interrupt
)
Check if an interrupt has been triggered.
Parameters
dev
The device to use
interrupt The interrupt to check
Warning
This function clears the current interrupt status bit
Returns
1 when interrupted, 0 when not interrupted, -1 otherwise
2.11.4.10
uart_enable_interrupt
int8_t uart_enable_interrupt ( ft900_uart_regs_t * dev,
uart_interrupt_t
interrupt
)
Enable an interrupt on the UART.
Parameters
dev
The device to use
interrupt The interrupt to enable
Returns
0 on success, -1 otherwise
2.11.4.11
uart_enable_interrupts_globally
int8_t uart_enable_interrupts_globally ( ft900_uart_regs_t * dev )
Enable a UART to interrupt.
Parameters
dev The device to use
Returns
0 on success, -1 otherwise
57
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.11.4.12
C learance N o.: FT DI#453
uart_disable_interrupt
int8_t uart_disable_interrupt ( ft900_uart_regs_t * dev,
uart_interrupt_t
interrupt
)
Disable an interrupt on the UART.
Parameters
dev
The device to use
interrupt The interrupt to disable
Returns
0 on success, -1 otherwise
2.11.4.13
uart_disable_interrupts_globally
int8_t uart_disable_interrupts_globally ( ft900_uart_regs_t * dev )
Disable a UART from interrupting.
Parameters
dev The device to use
Returns
0 on success, -1 otherwise
58
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.12 I2C Master
The file ft900_i2cm.h contains the definitions for the I2C master bus functions in the libft900.a
library.
2.12.1 API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.12.2 Enumeration Type Documentation
2.12.2.1 I2CM_speed_m ode
enum I2CM_speed_mode
Available speed modes.
Enumerator
I2CM_NORMAL_SPEED
Up to 100 kbps
I2CM_FAST_SPEED
Up to 400 kbps
I2CM_FAST_PLUS_SPEED
Up to 1000 kbps
I2CM_HIGH_SPEED
Up to 3400 kbps
2.12.3 Function Documentation
2.12.3.1 i2cm _init
void i2cm_init ( I2CM_speed_mode mode,
uint32_t
clk
)
Call once, to initialise the master and reset it to a known state.
It is not valid to call any other I2C Master functions before this one.
Parameters
[in] mode I2C Master Clock mode
[in] clk
The clock rate of the I2C bus
2.12.3.2 i2cm _read
int8_t i2cm_read ( const uint8_t
addr,
const uint8_t
cmd,
uint8_t *
data,
const uint16_t number_to_read
59
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
)
Read a specified number of bytes from an I2C device.
Automatically adopts burst mode if the slave supports it, and more than one byte is to be read.
Parameters
[in] addr
I2C address to write to.
[in] cmd
I2C command byte
[in] data
Buffer containing bytes to write.
[in] number_to_read Number of bytes to read.
Returns
0 on success, -1 on an error
2.12.3.3 i2cm _write
int8_t i2cm_write ( const uint8_t
addr,
const uint8_t
cmd,
const uint8_t *
data,
const uint16_t
number_to_write
)
Write a specified number of bytes to an I2C device.
Automatically adopts burst mode if the slave supports it, and more than one byte is t o be written.
Parameters
[in] addr
I2C address to write to.
[in] cmd
I2C command byte
[in] data
Buffer containing bytes to write.
[in] number_to_write Number of bytes to read.
Returns
2.12.3.4 0 on success, - 1 on an errori2cm _get_status
uint8_t i2cm_get_status ( void
)
Determine I2C Master status.
Bit
Mask Name
Set when...
0 (LSB)
MASK_I2CM_STATUS_I2C_BUSY
The Bus is currently busy transmitting/reveiving
1
MASK_I2CM_STATUS_I2C_ERR
An error occurred (ADDR_ACK, DATA_ACK,
ARB_LOST)
2
MASK_I2CM_STATUS_ADDR_ACK
Slave address was not acknowledged
3
MASK_I2CM_STATUS_DATA_ACK
Data was not acknowledged
4
MASK_I2CM_STATUS_ARB_LOST
Arbitration lost
60
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
5
MASK_I2CM_STATUS_I2C_IDLE
The I2C Controller is idle
6
MASK_I2CM_STATUS_BUS_BUSY
The I2C Bus is busy
7
(MSB)
-
-
C learance N o.: FT DI#453
Returns
0 on success, -1 on an error
2.12.3.5 i2cm _interrupt_disable
int8_t i2cm_interrupt_disable ( uint8_t
mask )
Disable an interrupt.
See also
i2cm_interrupt_enable
Parameters
mask The bit pattern of interrupts to disable
Returns
0 on success, -1 on an error
2.12.3.6 i2cm _interrupt_enable
int8_t i2cm_interrupt_enable ( uint8_t
mask )
Enable an interrupt.
Parameters
mask The bit pattern of interrupts to enable
Bit
Mask Name
Interrupts on...
0 (LSB)
MASK_I2CM_FIFO_INT_ENABLE_TX_EMPTY
When the Transmit FIFO is empty
1
MASK_I2CM_FIFO_INT_ENABLE_TX_HALF
When the Transmit FIFO is half empty
2
MASK_I2CM_FIFO_INT_ENABLE_TX_FULL
When the Transmit FIFO is full
3
MASK_I2CM_FIFO_INT_ENABLE_RX_EMPTY
When the Receive FIFO is empty
4
MASK_I2CM_FIFO_INT_ENABLE_RX_HALF
When the Receive FIFO is half full
5
MASK_I2CM_FIFO_INT_ENABLE_RX_FULL
When the Receive FIFO is full
6
MASK_I2CM_FIFO_INT_ENABLE_I2C_INT
When an operation is complete on the I2C
Master
7
(MSB)
MASK_I2CM_FIFO_INT_ENABLE_DONE
Returns
0 on success, -1 on an error
61
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.12.3.7 i2cm _is_interrupted
int8_t i2cm_is_interrupted ( uint8_t mask )
Check that an interrupt has been fired.
See also
i2cm_interrupt_enabled
Parameters
mask The bit pattern of interrupts to check
Returns
1 if the interrupt has been fired, 0 if the interrupt has not been fired, -1 otherwise
2.13 I2C Slave
The file ft900_i2cs.h contains the definitions for the I2C slave bus functions in the libft900.a
library.
2.13.1 API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.13.2 Function Documentation
2.13.2.1 i2cs_init
void i2cs_init ( uint8_t
addr )
Call once, to initialise the slave and reset it to a known state.
Parameters
[in]
addr
Slave (read or write) address
int8_t i2cs_is_interrupted ( uint8_t
mask
)
Check the status of an interrupt.
Parameters
mask The bit pattern of interrupts to check
Returns
1 if the interrupt has been fired, 0 if the interrupt has not been fired, -1 otherwise
62
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.13.2.2 i2cs_read
int8_t i2cs_read ( uint8_t * data,
size_t
size
)
Read a specified number of bytes from the I2C Slave.
This transaction is orchestrated by the I2C Master. The number of bytes written may be less than
the number requested if the master terminates the transaction early.
Parameters
[out] data Caller-allocated buffer to receive any bytes read.
[in]
size The number of bytes to read.
Returns
0 on success, -1 on an error
2.13.2.3 i2cs_write
int8_t i2cs_write ( const uint8_t *
size_t
data,
size
)
Write a specified number of bytes to an open device.
This transaction is orchestrated by the I2C Master. The number of bytes written may be less than
the number requested if the master terminates the transaction early.
Parameters
[in] data Buffer containing bytes to write.
[in] size The number of bytes to write.
Returns
0 on success, -1 on an error
63
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.13.2.4 i2cs_get_status
uint8_t i2cs_get_status ( void
)
Determine I2C Slave status.
Bit
Mask Name
Set when...
0 (LSB)
MASK_I2CS_STATUS_RX_REQ
The slave controller head received data
1
MASK_I2CS_STATUS_TX_REQ
The slave controller is transmitter and requires data
2
MASK_I2CS_STATUS_SEND_FIN
The master has ended the receive operation
3
MASK_I2CS_STATUS_REC_FIN
The master has ended the transmit operation
4
MASK_I2CS_STATUS_BUS_ACTV
The bus is currently busy with an operation
5
-
-
6
MASK_I2CS_STATUS_DEV_ACTV
The slave controller is enabled
7 (MSB)
-
-
Returns
Returns the status byte of the I2C Slave Status register
2.13.2.5 i2cs_disable_interrupt
int8_t i2cs_disable_interrupt ( uint8_t
mask )
Disable an interrupt.
Parameters
mask The bit pattern of interrupts to disable
Returns
0 on success, -1 on an error
2.13.2.6 i2cs_enable_interrupt
int8_t i2cs_enable_interrupt ( uint8_t
mask )
Enable an interrupt.
Parameters
mask The bit pattern of interrupts to enable
Returns
0 on success, -1 on an error
64
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.14 I2S Audio
The file ft900_i2s.h contains the definitions for the I2S bus functions in the libft900.a library.
2.14.1 API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.14.2 Enumeration Type Documentation
2.14.2.1 i2s_m ode_t
enum i2s_mode_t
I2S mode definitions.
Enumerator
i2s_mode_slave
I2S Slave
i2s_mode_master
I2S Master
2.14.2.2 i2s_form at_t
enum i2s_format_t
I2S format definitions.
Enumerator
i2s_format_i2s
I2S format
i2s_format_leftjust
Left justified format
i2s_format_rightjust
Right justified format
2.14.2.3 i2s_length_t
enum i2s_length_t
I2S data length definitions.
Enumerator
i2s_length_16
16 bit data length
i2s_length_20
20 bit data length
i2s_length_24
24 bit data length
i2s_length_32
32 bit data length
65
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.14.2.4 i2s_padding_t
enum i2s_padding_t
I2S padding definitions.
Enumerator
i2s_padding_0
No padding
i2s_padding_4
4 bits of padding
i2s_padding_8
8 bits of padding
i2s_padding_12
12 bits of padding
i2s_padding_16
16 bits of padding
2.14.2.5 i2s_bclk_div
enum i2s_bclk_div
I2S BCLK speed definitions.
Enumerator
i2s_bclk_div_1
Divide BCLK by 1
i2s_bclk_div_2
Divide BCLK by 2
i2s_bclk_div_3
Divide BCLK by 3
i2s_bclk_div_4
Divide BCLK by 4
i2s_bclk_div_6
Divide BCLK by 6
i2s_bclk_div_8
Divide BCLK by 8
i2s_bclk_div_12
Divide BCLK by 12
i2s_bclk_div_16
Divide BCLK by 16
i2s_bclk_div_24
Divide BCLK by 24
i2s_bclk_div_32
Divide BCLK by 32
i2s_bclk_div_48
Divide BCLK by 48
i2s_bclk_div_64
Divide BCLK by 64
2.14.2.6 i2s_m clk_div _t
enum i2s_mclk_div_t
I2S MCLK speed definitions.
66
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Enumerator
i2s_mclk_div_1
Divide MCLK by 1
i2s_mclk_div_2
Divide MCLK by 2
i2s_mclk_div_3
Divide MCLK by 3
i2s_mclk_div_4
Divide MCLK by 4
i2s_mclk_div_6
Divide MCLK by 6
i2s_mclk_div_8
Divide MCLK by 8
i2s_mclk_div_12
Divide MCLK by 12
i2s_mclk_div_16
Divide MCLK by 16
i2s_mclk_div_24
Divide MCLK by 24
i2s_mclk_div_32
Divide MCLK by 32
i2s_mclk_div_48
Divide MCLK by 48
i2s_mclk_div_64
Divide MCLK by 64
2.14.2.7 i2s_bclk_per_channel_t
enum i2s_bclk_per_channel_t
I2S BCLK cycles per channel, used in master mode only.
Enumerator
i2s_bclk_per_channel_16
16 BCLK per channel
i2s_bclk_per_channel_32
32 BCLK per channel
2.14.2.8 i2s_m aster_input_clk_t
enum i2s_master_input_clk_t
I2S master input clk frequency definitions.
Enumerator
i2s_master_input_clk_22mhz
22.5792 MHz Master clock
i2s_master_input_clk_24mhz
24.576 MHz Master clock
2.14.2.9 i2s_rx_t
enum i2s_rx_t
I2S RX definitions.
67
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Enumerator
i2s_rx_disabled
Receive Disabled
i2s_rx_enabled
Receive Enabled
2.14.2.10
i2s_tx_t
enum i2s_tx_t
I2S TX definitions.
Enumerator
i2s_tx_disabled
Transmit Disabled
i2s_tx_enabled
Transmit Enabled
2.14.3 Function Documentation
2.14.3.1 i2s_init
void i2s_init ( i2s_mode_t
mode,
i2s_length_t
length,
i2s_format_t
format,
i2s_padding_t
padding,
i2s_master_input_clk_t
mclk_in,
i2s_bclk_div
bclk_div,
i2s_mclk_div_t
mclk_div,
i2s_bclk_per_channel_t
bclk_per_channel
)
Call once, to initialise the peripheral and reset it to a known state.
Parameters
[in] mode
The I2S Mode
[in] length
The transfer length
[in] format
The format of the transfer
[in] padding
The number of padding bits that have the be added to the
transfer
[in] mclk_in
The MCLK to use
[in] bclk_div
The BCLK divider
[in] mclk_div
The MCLK divider
[in] bclk_per_channel The number of BCLK per channel
68
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.14.3.2 i2s_start_rx
void i2s_start_rx ( void
)
Start reception of the I2S Module.
2.14.3.3 i2s_start_tx
void i2s_start_tx ( void
)
Start transmission of the I2S Module.
2.14.3.4 i2s_stop_rx
void i2s_stop_rx ( void
)
Stop reception of the I2S Module.
2.14.3.5 i2s_stop_tx
void i2s_stop_tx ( void
)
Stop transmission of the I2S Module.
2.14.3.6 i2s_read
size_t i2s_read ( uint8_t *
const size_t
data,
num_bytes
)
Read a specified number of bytes from the I2S FIFO.
Reads x number of bytes from the I2S FIFO.
Parameters
[out] data
[in]
Caller-allocated buffer to receive any bytes read.
num_bytes Number of bytes to read from the FIFO.
2.14.3.7 i2s_write
size_t i2s_write ( const uint8_t * data,
const size_t
num_bytes
)
Write a specified number of bytes to the I2S FIFO.
Writes x number of bytes to the I2S FIFO.
Warning
Due to the hardw are implementation of I2S, there is a performance hit when using this function
with 24 bit input.
Parameters
[in] data
Buffer containing bytes to write.
[in] num_bytes Number of bytes to write to the FIFO.
69
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.14.3.8 i2s_get_status
uint16_t i2s_get_status ( void
)
Determine I2S status.
Get the status of the interrupts on the I2S module.
Returns
Returns the status of the I2S peripheral.
The copy of the Interrupt Status Register
2.14.3.9 i2s_get_rx_count
uint16_t i2s_get_rx_count ( void
)
Get the receive count of the I2S Module.
Returns
The number of receptions that have been made
2.14.3.10
i2s_get_tx_count
uint16_t i2s_get_tx_count ( void
)
Get the transmit count of the I2S Module.
Returns
The number of transmissions that have been made
2.14.3.11
i2s_disable_int
void i2s_disable_int ( uint16_t mask )
Disable interrupts on the I2S module.
Parameters
mask The mask of bits to disable
See also
i2s_enable_int
2.14.3.12
i2s_enable_int
void i2s_enable_int ( uint16_t mask )
Enable interrupts on the I2S module.
Bit
Mask Name
Interrupts when...
0 (LSB)
MASK_I2S_IE_FIFO_TX_UNDER
Transmit FIFO has underflowed
1
MASK_I2S_IE_FIFO_TX_EMPTY
Transmit FIFO is empty
2
MASK_I2S_IE_FIFO_TX_HALF_FULL
Transmit FIFO is half empty
3
MASK_I2S_IE_FIFO_TX_FULL
Transmit FIFO is full
4
MASK_I2S_IE_FIFO_TX_OVER
Transmit FIFO has overflowed
70
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
5
-
-
6
-
-
7
-
-
8
MASK_I2S_IE_FIFO_RX_UNDER
Receive FIFO has underflowed
9
MASK_I2S_IE_FIFO_RX_EMPTY
Receive FIFO is empty
10
MASK_I2S_IE_FIFO_RX_HALF_FULL
Receive FIFO is half empty
11
MASK_I2S_IE_FIFO_RX_FULL
Receive FIFO is full
12
MASK_I2S_IE_FIFO_RX_OVER
Receive FIFO has overflowed
13
-
-
14
-
-
15 (MSB)
-
-
Parameters
mask The mask of bits to enable
2.14.3.13
i2s_clear_int_flag
void i2s_clear_int_flag ( uint16_t mask )
Clear interrupt flags on the I2S module.
Parameters
mask The mask of bits to clear
2.14.3.14
i2s_is_interrupted
int8_t i2s_is_interrupted ( uint16_t mask )
Check if an interrupt has been fired.
Warning
This function will clear the current interrupts you are checking for
Parameters
mask The mask of interrupts to check for
Returns
1 when an interrupt has fired, 0 otherwise.
See also
i2s_enable_int
71
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.15 SPI Bus
The file ft900_spi.h contains the definitions for the SPI Master and Slave bus functions in the
libft900.a library.
2.15.1 API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.15.2 Enumeration Type Documentation
2.15.2.1 enum spi_clock_m ode_t
The SPI mode.
Enumerator
spi_mode_0
CPOL = 0, CPHA = 0
spi_mode_1
CPOL = 0, CPHA = 1
spi_mode_2
CPOL = 1, CPHA = 0
spi_mode_3
CPOL = 1, CPHA = 1
2.15.2.2 enum spi_option_t
SPI Options.
Enumerator
spi_option_fifo
Enable or disable the FIFO
spi_option_fifo_size
Set the size of the FIFO
spi_option_fifo_receive_trigger
Set the FIFO trigger level
spi_option_force_ss_assertions
Force SS to go low in assert
spi_option_bus_width
Set the SPI bus width
spi_option_multi_receive
Set the SPI device to clock in data without loading it into the RX
FIFO
spi_option_ignore_incoming
Not supported as of now.
2.15.2.3 enum spi_dir_t
SPI Direction.
Enumerator
spi_dir_slave
The SPI Device is in Slave mode
72
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
spi_dir_master
C learance N o.: FT DI#453
The SPI Device is in Master mode
2.15.2.4 enum spi_fifo_size_t
SPI FIFO size.
Enumerator
spi_fifo_size_16
Use a 16 level FIFO
spi_fifo_size_64
Use a 64 Byte FIFO
2.15.2.5 enum spi_width_t
SPI Data Bus Width.
Enumerator
spi_width_1bit
The SPI Device is working in 1 bit wide mode (i.e. 4 wire SPI)
spi_width_2bit
The SPI Device is working in 2 bit wide mode
spi_width_4bit
The SPI Device is working in 4 bit wide mode
2.15.2.6 enum spi_ss_assertions_t
SS Assertion control.
Enumerator
spi_ss_assertions_force
SS will reflect the status of SPISS
spi_ss_assertions_auto
SS will go low during transmissions if selected
2.15.2.7 enum spi_interrupt_t
SPI Interrupts
NOTE: Call spi_is_interrupted() to clear interrupt flags.
Enumerator
spi_interrupt_transmit_empty
Either the FIFO or the data register are empty.
spi_interrupt_data_ready
A transmission or reception was completed or the FIFO
was filled to a trigger level.
spi_interrupt_transmit_1bit_complete
Transmission was complete when using the SPI1BIT
method.
spi_interrupt_fault
The SPI device was asserted when in Master mode.
73
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.15.3 Function Documentation
2.15.3.1 spi_init
int8_t spi_init ( ft900_spi_regs_t * dev,
spi_dir_t
dir,
spi_clock_mode_t
clock_mode,
uint16_t
div
)
Initialise the SPI device.
Parameters
dev
the device to use
dir
The direction for the device to work in (Master/Slave)
clock_mode The SPI Clock mode to use
div
The clock divider to use (4,8,16,32,64,128,256,512)
Returns
0 on a success or -1 for a failure
Warning
This will reset the peripheral and all options
2.15.3.2 spi_open
int8_t spi_open ( ft900_spi_regs_t * dev,
uint8_t
num
)
Select a device to start communicating with.
Parameters
dev the device to use
num The device to select
Returns
0 on a success or -1 for a failure
2.15.3.3 spi_close
int8_t spi_close ( ft900_spi_regs_t * dev,
uint8_t
num
)
Stop communicating with a certain device.
Parameters
dev the device to use
74
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
num The device to select
Returns
0 on a success or -1 for a failure
2.15.3.4 spi_read
int32_t spi_read ( ft900_spi_regs_t * dev,
uint8_t
b
)
Reads a byte from the SPI device.
Reads a byte by writing a dummy byte into the SPI bus.
Parameters
dev the device to use
b
A variable to store the byte
Returns
The number of bytes read or -1 for a failure
2.15.3.5 spi_readn
int32_t spi_readn ( ft900_spi_regs_t * dev,
uint8_t *
b,
size_t
len
)
Reads several bytes from the SPI device.
Reads len number of bytes by writing len number of bytes into SPI bus.
Parameters
dev the device to use
b
A pointer to the array to read into
len The number of bytes to read
Returns
The number of bytes read or -1 for a failure
2.15.3.6 spi_write
int32_t spi_write ( ft900_spi_regs_t * dev,
uint8_t
b
)
Writes a byte to the SPI device.
Parameters
dev the device to use
75
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
b
C learance N o.: FT DI#453
The byte to send
Returns
The number of bytes written or -1 for a failure
2.15.3.7 spi_writen
int32_t spi_writen ( ft900_spi_regs_t * dev,
const uint8_t *
b,
size_t
len
)
Writes several bytes to the SPI device .
Parameters
dev the device to use
b
A pointer to the array to sendspi_open
len The number of bytes to write
Returns
The number of bytes written or -1 for a failure
2.15.3.8 spi_xchange
int32_t spi_xchange ( ft900_spi_regs_t * dev,
uint8_t
b,
uint8_t
c
)
Exchange a byte to the SPI device. Supports single channel mode only.
Parameters
dev the device to use
b
A variable to send the byte
c
A variable to store the byte
Returns
The number of bytes exchanged or -1 for failure.
2.15.3.9 spi_xchangen
int32_t spi_xchangen ( ft900_spi_regs_t * dev,
uint8_t *
binp,
uint8_t *
bout,
size_t
len
)
Exchange several bytes to the SPI device. Supports single channel mode only.
76
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
dev the device to use
binp A pointer to the array to send
bout A pointer to the array to receive
len
The number of bytes to exchange
Returns
2.15.3.10
The num ber of bytes exchanged or - 1 for a failurespi_status
uint8_t spi_status ( ft900_spi_regs_t * dev )
Return the status register.
Bit
Name
When set to 1
When set to 0
0
AUTOSS
Auto SS Assertions Enabled
SSO always shows contents of SSCR
1
RXFULL
Receiver FIFO is full
Receiver FIFO not is full
2
EMPTY
TX FIFO or TX register empty
TX FIFO or TX register not empty
3
IDLE
SPI Device Idle
Transmission in progress
4
FAULT
Mode Fault (SS Low in Master mode)
–
5
1BITTX
End of TX from SPDR BIS Register
–
6
WCOL
Data Register Write Collision occurred
–
7
IRQ
An interrupt occurred
–
Parameters
dev The device to use
Returns
A copy of the SPISTAT register
2.15.3.11
spi_option
int8_t spi_option ( ft900_spi_regs_t * dev,
spi_option_t
opt,
uint8_t
val
)
Control the SPI device.
This function will set various options for the driver.
Option
Description
Values
spim_option_fifo
Enable or disable the FIFO
0 = Disabled (Default)
1 = Enabled [Note 1]
spim_option_fifo_size
Set the size of the FIFO
16 = 16 Byte FIFO (default)
77
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
64 = Byte FIFO
spim_option_fifo_receive_trigger
Set the FIFO trigger level
For 16 Byte FIFOs: 1, 4, 8, 14
For 64 Byte FIFOs: 1, 16, 32, 56
spim_option_force_ss_assertions
Force SS to go low in assert
0 = Automatic Assertions
1 = Force Assertions (Default)
spim_option_bus_width
Set the SPI bus width
1 = Single (Default)
2 = Dual
4 = Quad
spim_option_dual_quad_direction
Set the multi-bit direction
0 = Read
1 = Write
Note 1: Enabling the FIFO will cause the driver to clear its contents.
Parameters
dev The device to use
opt The option to configure
val The value to use
Returns
0 on a success or -1 for a failure
2.15.3.12
spi_disable_interrupt
int8_t spi_disable_interrupt ( ft900_spi_regs_t * dev,
spi_interrupt_t
interrupt
)
Disables an interrupt for the SPI device.
Parameters
dev
The device to use
interrupt The interrupt to disable
Returns
0 on a success or -1 for a failure
See also
spim_disable_interrupts_globally
2.15.3.13
spi_disable_interrupts_globally
int8_t spi_disable_interrupts_globally ( ft900_spi_regs_t * dev )
Disables the SPI device from generating an interrupt.
Parameters
dev the device to use
Returns
0 on a success or -1 for a failure
78
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.15.3.14
C learance N o.: FT DI#453
spi_enable_interrupt
int8_t spi_enable_interrupt ( ft900_spi_regs_t * dev,
spi_interrupt_t
interrupt
)
Enables an interrupt for the SPI device.
Parameters
dev
the device to use
interrupt The interrupt to enable
Returns
0 on a success or -1 for a failure
See also
spim_enable_interrupts_globally
2.15.3.15
spi_enable_interrupts_globally
int8_t spi_enable_interrupts_globally ( ft900_spi_regs_t * dev )
Enables the SPI device to generate an interrupt.
Parameters
dev the device to use
Returns
0 on a success or -1 for a failure
2.15.3.16
spi_is_interrupted
int8_t spi_is_interrupted ( ft900_spi_regs_t * dev,
spi_interrupt_t
interrupt
)
Disables an interrupt for the QSPI device.
Parameters
dev
The device to use
interrupt The interrupt to check
Returns
1 when interrupted, 0 when not interrupted, -1 otherwise
See also
spi_disable_interrupts_globally
79
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.15.3.17
C learance N o.: FT DI#453
spi_uninit
int8_t spi_uninit ( ft900_spi_regs_t * dev )
Disable the SPI device.
Parameters
dev the device to use
Returns
0 on a success or -1 for a failure
2.16 CANBus
The file ft900_can.h contains the definitions for the CANBus functions in the libft900.a library.
2.16.1 API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.16.2 Enumeration Type Documentation
2.16.2.1 can_m ode_t
enum can_mode_t
The mode of the CAN device.
Enumerator
can_mode_normal
The CAN Device is operating normally
can_mode_listen
The CAN Device is in listen-only mode and will not allow data transmission or
send ACKs on the bus
2.16.2.2 can_type_t
enum can_type_t
CAN message type.
Enumerator
can_type_standard
CAN2.0A Standard Frame
can_type_extended
CAN2.0B Extended Frame
2.16.2.3 can_filter_m ode_t
enum can_filter_mode_t
The mode of the filter.
80
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Enumerator
can_filter_mode_single
Single Filter mode
can_filter_mode_dual
Dual Filter mode
2.16.2.4 can_arbitration_lost_t
enum can_arbitration_lost_t
The location of where arbitration was lost.
Enumerator
can_arbitration_lost_id28_11
Arbitration was lost on the 12th bit of the ID (29th bit extended)
can_arbitration_lost_id27_10
Arbitration was lost on the 11th bit of the ID (28th bit extended)
can_arbitration_lost_id26_9
Arbitration was lost on the 10th bit of the ID (27th bit extended)
can_arbitration_lost_id25_8
Arbitration was lost on the 9th bit of the ID (26th bit extended)
can_arbitration_lost_id24_7
Arbitration was lost on the 8th bit of the ID (25th bit extended)
can_arbitration_lost_id23_6
Arbitration was lost on the 7th bit of the ID (24th bit extended)
can_arbitration_lost_id22_5
Arbitration was lost on the 6th bit of the ID (23th bit extended)
can_arbitration_lost_id21_4
Arbitration was lost on the 5th bit of the ID (22th bit extended)
can_arbitration_lost_id20_3
Arbitration was lost on the 4th bit of the ID (21th bit extended)
can_arbitration_lost_id19_2
Arbitration was lost on the 3rd bit of the ID (20th bit extended)
can_arbitration_lost_id18_1
Arbitration was lost on the 2nd bit of the ID (19th bit extended)
can_arbitration_lost_id17_0
Arbitration was lost on the 1st bit of the ID (18th bit extended)
can_arbitration_lost_srtr_rtr
Arbitration was lost on the SRTR/RTR bit
can_arbitration_lost_id16
Arbitration was lost on the 17th bit of the extended ID
can_arbitration_lost_id15
Arbitration was lost on the 16th bit of the extended ID
can_arbitration_lost_id14
Arbitration was lost on the 15th bit of the extended ID
can_arbitration_lost_id13
Arbitration was lost on the 14th bit of the extended ID
can_arbitration_lost_id12
Arbitration was lost on the 13th bit of the extended ID
can_arbitration_lost_id11
Arbitration was lost on the 12th bit of the extended ID
can_arbitration_lost_id10
Arbitration was lost on the 11th bit of the extended ID
can_arbitration_lost_id9
Arbitration was lost on the 10th bit of the extended ID
81
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
can_arbitration_lost_id8
Arbitration was lost on the 9th bit of the extended ID
can_arbitration_lost_id7
Arbitration was lost on the 8th bit of the extended ID
can_arbitration_lost_id6
Arbitration was lost on the 7th bit of the extended ID
can_arbitration_lost_id5
Arbitration was lost on the 6th bit of the extended ID
can_arbitration_lost_id4
Arbitration was lost on the 5th bit of the extended ID
can_arbitration_lost_id3
Arbitration was lost on the 4th bit of the extended ID
can_arbitration_lost_id2
Arbitration was lost on the 3rd bit of the extended ID
can_arbitration_lost_id1
Arbitration was lost on the 2nd bit of the extended ID
can_arbitration_lost_id0
Arbitration was lost on the 1st bit of the extended ID
can_arbitration_lost_rtr
Arbitration was lost on the RTR bit
can_arbitration_lost_invalid
No valid arbitration could be found
2.16.2.5 can_interrupt_t
enum can_interrupt_t
CAN Peripheral Interrupts.
Enumerator
can_interrupt_data_overrun
can_interrupt_bus_error
can_interrupt_transmit
can_interrupt_receive
can_interrupt_error_passive
can_interrupt_error_warning
can_interrupt_arbitration_lost
2.16.2.6 can_rtr_t
enum can_rtr_t
Remote transfer request flag.
Enumerator
can_rtr_none
No RTR
can_rtr_remote_request
RTR Set
82
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.16.3 Function Documentation
2.16.3.1 can_init
int8_t can_init ( ft900_can_regs_t *
dev,
can_mode_t
mode,
const can_time_config_t *
timeconfig
)
Initialise the CAN device.
Parameters
dev
A pointer to the device to use
mode
The mode that this CAn device should be in (normal or listen)
timeconfig The configuration struct that defines the timing of the device
Returns
0 on a success, -1 otherwise
2.16.3.2 can_open
int8_t can_open ( ft900_can_regs_t * dev )
Open the CAN device for reading and writing.
Parameters
dev A pointer to the device to use
Returns
0 on a success, -1 otherwise
2.16.3.3 can_close
int8_t can_close ( ft900_can_regs_t * dev )
Close the CAN device for reading and writing.
Parameters
dev A pointer to the device to use
Returns
0 on a success, -1 otherwise
2.16.3.4 can_filter
int8_t can_filter ( ft900_can_regs_t *
dev,
can_filter_mode_t
filtmode,
uint8_t
filternum,
const can_filter_t * filter
)
Set up a filter for the CAN device.
83
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Set up the CAN device to filter for specific criteria.
The filter can work in two modes: single or dual. Depending on which mode the filter is in certain
types of information can be used, as shown in the table below.
Mode
Message Type
ID
RTR
Data[0]
Data[1]
Single
Standard
Yes
Yes
Yes
Yes
Single
Extended
Yes
Yes
No
No
Dual
Standard
Yes
Yes
Filter 0 Only
No
Dual
Extended
Only bits 13 to 28
No
No
No
Any field which is not used in a certain configuration will be ignored.
Parameters
dev
A pointer to the device to use
filtmode
The mode that the filters should be in (single or dual)
filternum The number of filter to use. When in single mode, only 0 will work.
filter
A pointer to the configuration to use
Returns
0 on a success, -1 otherwise
Warning
This command only works when the CAN device is closed
See also
can_filter_t
2.16.3.5 can_read
int8_t can_read ( ft900_can_regs_t * dev,
can_msg_t *
msg
)
Receive a message from the CAN Bus.
This function will take the first available message from the Receive FIFO.
Parameters
dev A pointer to the device to use
msg The struct to pack the message into
Returns
0 on a success, -1 otherwise
Warning
This command only works when the CAN device is open
This function will automatically clear the Receive interrupt flag and increment the Receive message
counter.
84
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.16.3.6 can_write
int8_t can_write ( ft900_can_regs_t * dev,
const can_msg_t *
msg
)
Send a message on the CAN Bus.
This function will accept a can_msg_t and pack it into a format to be fed into the CAN Transmit
FIFO.
Parameters
dev A pointer to the device to use
msg The message to send
Returns
0 on a success, -1 otherwise
Warning
This command only works when the CAN device is open
2.16.3.7 can_abort
int8_t can_abort ( ft900_can_regs_t * dev )
Abort the transmission of messages on the CAN Bus.
This function will cause the CAN device to abort transmission on the CAN Bus. After the
transmission of the current message on the Bus, no further transmissions will occur (including
retransmissions for erroneous messages).
Parameters
dev A pointer to the device to use
Returns
0 on a success, -1 otherwise
2.16.3.8 can_status
uint8_t can_status ( ft900_can_regs_t * dev )
Query the status register.
The return value is a bit-mask with the following format:
Bit
Name
Description
Set when...
7
(MSB)
RX_BUF_STS
Receive Buffer Status
At least one message in the receive FIFO
6
OVRN_STS
Data Overrun Status
The receive FIFO has encountered an overrun
5
TX_BUF_STS
Transmit Buffer
Status
The CPU is able to write to the transmit FIFO
4
-
3
RX_STS
Receive Status
CAN is currently receiving a message
85
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2
TX_STS
Transmit Status
CAN is currently transmitting a message
1
ERR_STS
Error Status
One CAN error counter has reached warning
(96)
0 (LSB)
BUS_OFF_STS
Bus Off Status
The CAN device is in a bus off state
Parameters
dev A pointer to the device to use
Returns
A bit-mask of the current status or 0 for an unknown device.
2.16.3.9 can_available
uint8_t can_available ( ft900_can_regs_t * dev )
Return how many messages are available in the receive FIFO.
Parameters
dev A pointer to the device to use
Returns
The number of messages available in the receive FIFO
2.16.3.10
can_rx_error_count
uint8_t can_rx_error_count ( ft900_can_regs_t * dev )
Get the current number of receive errors reported by the CAN device.
Parameters
dev A pointer to the device to use
Returns
The current number of receive errors (0 - 255) or 0 for an unknown device.
2.16.3.11
can_tx_error_count
uint8_t can_tx_error_count ( ft900_can_regs_t * dev )
Get the current number of transmit errors reported by the CAN device.
When the transmit error counter exceeds limit of 255, the Bus Status bit in the Stat us register is
set to logic 1 (bus off), the CAN controller set reset mode, and if enabled an error warning
interrupt is generated. The transmit error counter is then set to 127 and receive error counter is
cleared.
Parameters
dev A pointer to the device to use
Returns
The current number of receive errors (0 - 255) or 0 for an unknown device.
2.16.3.12
can_ecode
uint8_t can_ecode ( ft900_can_regs_t * dev )
86
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Get the current value of the ECC (Error Code Capture) register.
This function will return the value of the ECC (Error Code Capture) register. This register holds the
error code for the LAST bus error that occurred on the CAN network.
The return value is a bit-mask with the following format:
Bit
Name
Description
Set when...
7 (MSB)
RX_WRN
Receive Warning
The number of receive errors is >= 96
6
TX_WRN
Transmit Warning
The number of transmit errors is >= 96
5
ERR_DIR
Direction
The error occurred on reception.
4
ACK_ERR
Acknowledgement Error
An ACK Error occurred
3
FRM_ERR
Form Error
A Form Error occurred
2
CRC_ERR
CRC Error
A CRC Error occurred
1
STF_ERR
Stuff Error
A Bit Stuffing Error occurred
0 (LSB)
BIT_ERR
Bit Error
A Bit Error occurred
Parameters
dev A pointer to the device to use
Returns
The value of the ECC (Error Code Capture) register or 0 for an unknown device.
2.16.3.13
can_arbitration_lost_location
can_arbitration_lost_t can_arbitration_lost_location ( ft900_can_regs_t * dev )
Get the location where arbitration was lost.
Parameters
dev A pointer to the device to use
Returns
The location where arbitration was lost
2.16.3.14
can_enable_interrupt
int8_t can_enable_interrupt ( ft900_can_regs_t * dev,
can_interrupt_t
interrupt
)
Enable an Interrupt.
Enable the CAN device to generate an interrupt. The value of mask is a bit-mask with the following
format:
Bit
Name
7
(MSB)
Description
Trigger
Unused
87
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
6
ARB_LOST
Arbitration Lost
Interrupt
Arbitration is lost
5
ERR_WARN
Error Warning Interrupt
Changes in ES or BS of the Status register
4
ERR_PSV
Error Passive Interrupt
Bus enters or exits a passive state
3
RX
Receive Interrupt
A message is received on CAN
2
TX
Transmit Interrupt
A message is successfully received on CAN
1
BUS_ERR
Bus Error Interrupt
A bus error occurred when
transmitting\receiving
0 (LSB)
DATA_OVRN
Data Overrun Interrupt
A receive FIFO overrun occurred
Parameters
dev
A pointer to the device to use
interrupt The interrupt to enable
Returns
0 on a success, -1 otherwise
Warning
This command only works when the CAN device is closed
2.16.3.15
can_disable_interrupt
int8_t can_disable_interrupt ( ft900_can_regs_t * dev,
can_interrupt_t
interrupt
)
Disable an Interrupt.
Disable the CAN device from generate an interrupt.
Parameters
dev
A pointer to the device to use
interrupt The interrupt to disable
Returns
0 on a success, -1 otherwise
Warning
This command only works when the CAN device is closed
88
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.16.3.16
C learance N o.: FT DI#453
can_is_interrupted
int8_t can_is_interrupted ( ft900_can_regs_t * dev,
can_interrupt_t
interrupt
)
Query the Interrupt register.
Query the Interrupt register in order to determine what caused the interrupt.
Parameters
dev
A pointer to the device to use
interrupt The interrupt to check
Warning
This function clears the interrupt bit so that it does not fire constantly
Returns
0 when the interrupt hasn't been fired, 1 when the interrupt has fired and -1 otherwise
2.16.4 Variable Documentation
const can_time_config_t g_can125kbaud
Configuration for 125 kBaud at fcpu = 100 MHz
const can_time_config_t g_can1Mbaud
Configuration for 1 MBaud at fcpu = 100 MHz
const can_time_config_t g_can250kbaud
Configuration for 250 kBaud at fcpu = 100 MHz
const can_time_config_t g_can500kbaud
Configuration for 500 kBaud at fcpu = 100 MHz
89
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.17 Camera interface
The file ft900_cam.h contains the definitions for the camera bus functions in the libft900.a
library.
2.17.1 API Cross Reference
It utilises the following library APIs:
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.17.2 Enumeration Type Documentation
2.17.2.1 cam_clock_pol_t
enum cam_clock_pol_t
Camera clock polarity.
Enumerator
cam_clock_pol_falling
Sample data on a falling PCLK edge
cam_clock_pol_raising
Sample data on a raising PCLK edge
2.17.2.2 cam_trigger_mode_t
enum cam_trigger_mode_t
Camera vertical/horizontal trigger mode Control at what logic levels the camera will accept data.
Enumerator
cam_trigger_mode_0
VD = L, HD = L
cam_trigger_mode_1
VD = L, HD = H
cam_trigger_mode_2
VD = H, HD = L
cam_trigger_mode_3
VD = H, HD = H
2.17.3 Function Documentation
2.17.3.1 cam _init
int8_t cam_init ( cam_trigger_mode_t triggers,
cam_clock_pol_t
clkpol
)
Initialise the Camera interface.
Parameters
triggers The VD/HD levels to trigger on
90
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
clkpol
C learance N o.: FT DI#453
The clock polarity of the input
Returns
0 on success, -1 otherwise
2.17.3.2 cam _available
uint16_t cam_available ( void
)
Check how many bytes are available on the FIFO.
Returns
The number of bytes available
2.17.3.3 cam _start
int8_t cam_start ( uint16_t bytes )
Start capturing data.
Parameters
bytes The number of bytes to capture
Returns
0 on success, -1 otherwise
2.17.3.4 cam _stop
int8_t cam_stop ( void
)
Stop capturing data.
Returns
0 on success, -1 otherwise
2.17.3.5 cam _set_threshold
int8_t cam_set_threshold ( uint16_t n )
Set the threshold for when the camera interrupt fires.
Parameters
n The number of bytes to fill the FIFO with before the interrupt fires (this must be a
multiple of 4)
Returns
0 on success, -1 otherwise
2.17.3.6 cam _readn
uint16_t cam_readn ( uint8_t * b,
size_t
len
)
Read a number of bytes from the FIFO.
Parameters
91
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
b
C learance N o.: FT DI#453
A pointer to read the data into
len The number of bytes to read from the FIFO (this must be a multiple of 4)
Returns
The number of bytes read, 0 otherwise
2.17.3.7 cam _flush
void cam_flush ( void
)
Empty out the camera buffer.
2.17.3.8 cam _total_read
uint16_t cam_total_read ( void
)
Check how many bytes have been read by the Camera Interface.
Returns
2.17.3.9 The num ber of bytes readcam _enable_interrupt
int8_t cam_enable_interrupt ( void
)
Enable the threshold interrupt.
Returns
0 on success, -1 otherwise
2.17.3.10
cam _disable_interrupt
int8_t cam_disable_interrupt ( void
)
Disable the threshold interrupt.
Returns
0 on success, -1 otherwise
2.17.3.11
cam _is_interrupted
int8_t cam_is_interrupted ( void
)
Check that an interrupt has occurred.
Returns
0 when the interrupt hasn't been fired, 1 when the interrupt has fired and -1 otherwise
92
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.18 Pulse Width Modulation
The file ft900_pwm.h contains the definitions for the Pulse Width Modulation functions in the
libft900.a library.
2.18.1 API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.18.2 Enumeration Type Documentation
2.18.2.1 pwm _restore_t
enum pwm_restore_t
PWM restore state.
Enumerator
pwm_restore_disable
Do not restore the setup state on wrap around
pwm_restore_enable
Do not restore the setup state on wrap around
2.18.2.2 pwm _state_t
enum pwm_state_t
Enumerator
pwm_state_low
Setup as low
pwm_state_high
Setup as high
2.18.2.3 pwm _trigger_t
enum pwm_trigger_t
PWM Triggering.
Enumerator
pwm_trigger_disabled
Do not trigger
pwm_trigger_positive_edge
Trigger on a positive edge
pwm_trigger_negative_edge
Trigger on a negative edge
pwm_trigger_any_edge
Trigger on any edge
2.18.3 Function Documentation
2.18.3.1 pwm _init
int8_t pwm_init ( uint8_t
prescaler,
93
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
uint16_t maxcount,
uint8_t
shots
)
Initialise the PWM subsystem.
Parameters
prescaler The prescaler for the PWM subsystem
maxcount The maximum count of the 16 bit master counter
shots
The number of loops the PWM subsystem will make, 0 is infinity
Returns
On success a 0, otherwise -1
2.18.3.2 pwm _enable
int8_t pwm_enable ( void
)
Enable the PWM subsystem.
Returns
On success a 0, otherwise -1
2.18.3.3 pwm _disable
int8_t pwm_disable ( void
)
Disable the PWM subsystem.
Returns
On success a 0, otherwise -1
2.18.3.4 pwm _add_toggle
int8_t pwm_add_toggle ( uint8_t channel,
uint8_t toggle
)
Add a toggle to a specific PWM channel.
Parameters
channel The channel to add the toggle to
toggle
The channel to toggle on
Returns
On success a 0, otherwise -1
2.18.3.5 pwm _rem ove_toggle
int8_t pwm_remove_toggle ( uint8_t
uint8_t
channel,
toggle
)
94
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Remove a toggle to a specific PWM channel.
Parameters
channel The channel to remove the toggle from
toggle
The channel to remove the toggle of
Returns
On success a 0, otherwise -1
2.18.3.6 pwm _com pare
int8_t pwm_compare ( uint8_t
channel,
uint16_t value
)
Set a compare value for a PWM counter.
Parameters
channel The channel to use
value
The value to toggle on
Returns
On success a 0, otherwise -1
2.18.3.7 pwm _lev els
int8_t pwm_levels ( uint8_t
pwm_state_t
channel,
initstate,
pwm_restore_t restorestate
)
Set up the logic levels for a PWM counter.
Parameters
channel
The channel to use
initstate
The initial state of the counter (high or low)
restorestate The rollover restore setting
Returns
On success a 0, otherwise -1
95
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.18.3.8 pwm _trigger
int8_t pwm_trigger ( pwm_trigger_t trigger )
Set the external trigger settings.
Parameters
trigger The trigger setting
Returns
On success a 0, otherwise -1
96
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.19 PWM Audio
The file ft900_pwm_pcm.h contains the definitions for the PWM audio functions in the libft900.a
library.
2.19.1 API Cross Reference
It utilises the following library APIs:
ft900_pwm.h – Pulse Width Modulation
ft900_asm.h – FT900 assembler definitions
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.19.2 Enumeration Type Documentation
2.19.2.1 pwm _pcm _channels_t
enum pwm_pcm_channels_t
PWM Channel selection.
Enumerator
pwm_pcm_channels_mono
Mono
pwm_pcm_channels_stereo
Stereo
2.19.2.2 pwm _pcm _data_size_t
enum pwm_pcm_data_size_t
PWM data size selection.
Enumerator
pwm_pcm_data_size_8
8 bit
pwm_pcm_data_size_16
16 bit
2.19.2.3 pwm _pcm _endianness_t
enum pwm_pcm_endianness_t
PWM endianness selection.
Enumerator
pwm_pcm_endianness_big
Big endian data
pwm_pcm_endianness_little
Little endian data
2.19.2.4 pwm _pcm _filter_t
enum pwm_pcm_filter_t
PWM PCM Filter.
97
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Enumerator
pwm_pcm_filter_off
Off
pwm_pcm_filter_on
On
2.19.2.5 pwm _pcm _interrupt_t
enum pwm_pcm_interrupt_t
PWM PCM Interrupt selection.
Enumerator
pwm_pcm_interrupt_empty
FIFO Empty
pwm_pcm_interrupt_full
FIFO Full
pwm_pcm_interrupt_half_full
FIFO Half Full
pwm_pcm_interrupt_overflow
FIFO Overflow
pwm_pcm_interrupt_underflow
FIFO Underflow
2.19.2.6 pwm _pcm _volume_t
enum pwm_pcm_volume_t
PWM PCM Volume.
Enumerator
pwm_pcm_volume_mute
pwm_pcm_volume_6
6.25% volume
pwm_pcm_volume_12
12.5% volume
pwm_pcm_volume_19
19% volume
pwm_pcm_volume_25
25% volume
pwm_pcm_volume_31
31% volume
pwm_pcm_volume_37
37% volume
pwm_pcm_volume_44
44% volume
pwm_pcm_volume_50
50% volume
pwm_pcm_volume_56
56% volume
pwm_pcm_volume_63
63% volume
pwm_pcm_volume_69
69% volume
98
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
pwm_pcm_volume_75
75% volume
pwm_pcm_volume_81
81% volume
pwm_pcm_volume_88
88% volume
pwm_pcm_volume_94
94% volume
pwm_pcm_volume_100
100% volume
C learance N o.: FT DI#453
2.19.3 Function Documentation
2.19.3.1 pwm _pcm _open
int8_t pwm_pcm_open ( pwm_pcm_channels_t
channels,
uint16_t
samplerate,
pwm_pcm_data_size_t
datasize,
pwm_pcm_endianness_t
endianness,
pwm_pcm_filter_t
filter
)
Initialise the PWM PCM output.
Parameters
channels
The number of channels to output.
samplerate The sample rate of the audio data.
datasize
The word size of the samples (8 or 16 bit).
endianness The endianness of the 16 bit word. In 8 bit mode this will be ignored.
filter
If a PCM filter will be used to filter out the PWM carrier.
Returns
On success a 0, otherwise -1
2.19.3.2 pwm _pcm _close
int8_t pwm_pcm_close ( void
)
Close the PWM PCM Output.
Returns
On success a 0, otherwise -1
2.19.3.3 pwm _pcm _volume
int8_t pwm_pcm_volume ( pwm_pcm_volume_t
vol )
Set the volume of the PWM PCM device.
Parameters
vol The volume to set to.
99
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
On success a 0, otherwise -1
2.19.3.4 pwm _pcm _write
int8_t pwm_pcm_write ( uint16_t data )
Write a word of data to the PWM PCM device.
Parameters
data The data to write. If 8 bit mode is selected, the top 8 bits will be ignored
Returns
The number of bytes written to the FIFO, otherwise -1
2.19.3.5 pwm _pcm _writen
int8_t pwm_pcm_writen ( uint16_t * data,
size_t
len
)
Write a number of words of data to the PWM PCM device.
Parameters
data The data to write. If 8 bit mode is selected, the top 8 bits will be ignored
len
The size of data to write.
Returns
2.19.3.6 The num ber of bytes written to the FIFO, otherwise 1pwm _pcm _disable_interrupt
int8_t pwm_pcm_disable_interrupt ( pwm_pcm_interrupt_t
interrupt )
Disable an interrupt.
Parameters
interrupt The interrupt to disable
Returns
On success a 0, otherwise -1
2.19.3.7 pwm _pcm _enable_interrupt
int8_t pwm_pcm_enable_interrupt ( pwm_pcm_interrupt_t
interrupt )
Enable an interrupt.
Parameters
interrupt The interrupt to enable
Returns
On success a 0, otherwise -1
100
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.19.3.8 pwm _pcm _is_interrupted
int8_t pwm_pcm_is_interrupted ( pwm_pcm_interrupt_t
interrupt )
Query if an interrupt has fired.
Parameters
interrupt The interrupt to query
Warning
This function will clear the interrupt being queried and the global PWM interrupt flag
Returns
1 for if PWM is interrupted, 0 if PWM is not interrupted, -1 otherwise
101
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.20 Real Time Clock
The file ft900_rtc.h contains the definitions for the real time clock functions in the libft900.a
library.
2.20.1 API Cross Reference
Additional definitions are taken from:
ft900_registers.h – FT900 register definitions
2.20.2 Enumeration Type Documentation
2.20.2.1 rtc_m ask_t
enum rtc_mask_t
RTC Interrupt mask.
Enumerator
rtc_mask_interrupt
Interrupt line is masked on interrupt
rtc_mask_no_interrupt
Interrupt line is not masked on interrupt
2.20.2.2 rtc_wrap_t
enum rtc_wrap_t
RTC Wrap around.
Enumerator
rtc_wrap_disabled
RTC Wrap around
rtc_wrap_enabled
No RTC Wrap around
2.20.3 Function Documentation
2.20.3.1 rtc_init
int8_t rtc_init ( rtc_wrap_t
wrap )
Initialise the Real Time Clock.
Parameters
wrap An option to control if the counter should wrap around
Returns
0 on success, -1 otherwise
2.20.3.2 rtc_start
int8_t rtc_start ( void
)
Allow the Real Time Clock to start counting.
Returns
102
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
0 on success, -1 otherwise
2.20.3.3 rtc_stop
int8_t rtc_stop ( void
)
Stops the Real Time Clock from counting.
Returns
0 on success, -1 otherwise
2.20.3.4 rtc_read
int8_t rtc_read ( uint32_t *
val )
Read the current value of the Real Time Clock.
Parameters
val A pointer to store the current Real Time Clock Value into
Returns
0 on success, -1 otherwise
2.20.3.5 rtc_write
int8_t rtc_write ( uint32_t val )
Set the Real Time Clock to a value.
Parameters
val The value to set the Real Time Clock to
Returns
2.20.3.6 0 on success, - 1 otherwisertc_m atch
int8_t rtc_match ( uint32_t
match,
rtc_mask_t mask
)
Set up the matching system in the Real Time Clock.
Parameters
match The value to match the Real Time Clock to
mask Defines whether the Real Time Clock module should mask the match interrupt line
Returns
0 on success, -1 otherwise
2.20.3.7 rtc_clear_m atched
int8_t rtc_clear_matched ( )
Clear the matched interrupt in the Real Time Clock.
Returns
0 on success, -1 otherwise
103
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.20.3.8 rtc_is_m atched
int8_t rtc_is_matched ( void
)
Check if the Real Time Clock has matched a value.
Warning
This function will clear the current interrupt. The value returned by this function is after masking.
Returns
1 if the Real Time Clock has matched, 0 otherwise
2.20.3.9 rtc_is_m atched_raw
int8_t rtc_is_matched_raw ( void
)
Check if the Real Time Clock has matched a value.
Returns
1 if the Real Time Clock has matched, 0 otherwise
104
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.21 USB Device Stack API
The file ft900_usbd.h contains the definitions for the USB device functions in the libft900.a
library.
This contains USB Device API function definitions, constants and structures which a re exposed in
the API.
Note that as this is a USB device all transaction nomenclature is from the point of view from the
host. If the device sends data to the host then it is called an IN transaction, if it receives data from
the host then it is an OUT transaction.
2.21.1 API Cross Reference
Utilises the following library APIs:
ft900_gpio.h – General Purpose I/O and Pad Control
ft900_sys.h – Chip Management
ft900_delay.h – Delay
ft900_interrupt.h – Interrupt Management
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_registers.h – FT900 register definitions
2.21.2 Macro Definition Documentation
2.21.2.1 USB Dev ice Error Codes
#define USBD_ERR_DISCONNECTED
-10
Device not configured by host.
Device physically disconnected from host.
#define USBD_ERR_INCOMPLETE
-5
Incomplete/interrupted transfer.
#define USBD_ERR_RESOURCES
-4
Not enough endpoint resources.
#define USBD_ERR_NOT_SUPPORTED
-3
Operation not supported.
#define USBD_ERR_NOT_CONFIGURED
-2
Endpoint not configured.
#define USBD_ERR_INVALID_PARAMETER
-1
Invalid parameter supplied to API function.
105
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.21.3 Typedef Documentation
2.21.3.1 USBD_reset_callback
typedef void(*
USBD_reset_callback) (uint8_t status)
Callback declaration for a host reset.
Parameters
[in] status Unused.
2.21.3.2 USBD_suspend_callback
typedef void(*
USBD_suspend_callback) (uint8_t status)
Callback declaration for a suspend/resume.
Parameters
[in] status Unused.
2.21.3.3 USBD_request_callback
typedef int8_t(*
USBD_request_callback) (USB_device_request *req)
Callback declaration for Vendor, Class and optionally Standard USB requests.
Parameters
[in] req USB request.
Returns
USBD_OK if the request was handled successfully; any other return value (such as FT9XX_FAILED)
causes the USB driver to stall the control endpoints.
2.21.3.4 USBD_descriptor_callback
typedef int8_t(*
USBD_descriptor_callback) (USB_device_request *req, uint8_t
**buffer, uint16_t *len)
Callback declaration for standard get descriptor requests to obtain descriptor data.
Parameters
[in] req
USB request.
[in] buffer Data buffer containing descriptor.
Returns
USBD_OK if the request was handled successfully; any other return value (such as FT9XX_FAILED)
causes the USB driver to stall the control endpoints.
2.21.3.5 USBD_ep_callback
typedef void(*
USBD_ep_callback) (USBD_ENDPOINT_NUMBER ep_number)
Callback declaration for transaction completion on endpoint. The endpoint number is passed to the
callback to allow the same function to handle multiple endpoints.
106
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.21.4 Enumeration Type Documentation
2.21.4.1 USBD_STATE
enum USBD_STATE
USB States. USB Spec section 9.1.
Enumerator
USBD_STATE_NONE
Device is not attached.
USBD_STATE_ATTACHED
Device is attached to USB.
USBD_STATE_POWERED
Device is attached and powered.
USBD_STATE_DEFAULT
Device is attached, has power and has been reset.
USBD_STATE_ADDRESS
Unique device address has not been set.
USBD_STATE_CONFIGURED
Unique device address is now assigned. Device can be used by
host.
USBD_STATE_SUSPENDED
Device has been suspended.
2.21.4.2 USBD_DEVICE_SPEED
enum USBD_DEVICE_SPEED
USB Endpoint Speed setting.
Enumerator
USBD_SPEED_FULL
Full speed.
USBD_SPEED_HIGH
High speed.
2.21.4.3 USBD_ENDPOINT_NUMBER
enum USBD_ENDPOINT_NUMBER
USB Endpoint Numbers.
Enumerator
USBD_EP_0
Endpoint 0 (Control Endpoint)
USBD_EP_1
Endpoint 1.
USBD_EP_2
Endpoint 2.
USBD_EP_3
Endpoint 3.
USBD_EP_4
Endpoint 4.
USBD_EP_5
Endpoint 5.
107
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
USBD_EP_6
Endpoint 6.
USBD_EP_7
Endpoint 7.
C learance N o.: FT DI#453
2.21.4.4 USBD_ENDPOINT_DIR
enum USBD_ENDPOINT_DIR
USB Endpoint Direction.
Enumerator
USBD_DIR_OUT
Direction host to device.
USBD_DIR_IN
Direction device to host.
2.21.4.5 USBD_ENDPOINT_SIZE
enum USBD_ENDPOINT_SIZE
USB Endpoint Sizes.
Enumerator
USBD_EP_SIZE_8
8 Bytes
USBD_EP_SIZE_16
16 Bytes
USBD_EP_SIZE_32
32 Bytes
USBD_EP_SIZE_64
64 Bytes
USBD_EP_SIZE_128
128 Bytes. Only available on High Speed endpoints.
USBD_EP_SIZE_256
256 Bytes. Only available on High Speed endpoints.
USBD_EP_SIZE_512
512 Bytes. Only available on High Speed endpoints.
USBD_EP_SIZE_1024
1024 Bytes. Only available on ISO endpoints.
2.21.4.6 USBD_ENDPOINT_TYPE
enum USBD_ENDPOINT_TYPE
USB Endpoint Types.
Enumerator
USBD_EP_TYPE_DISABLED
Disabled.
USBD_EP_BULK
Bulk Endpoint.
USBD_EP_INT
Interrupt Endpoint.
USBD_EP_ISOC
Isochronous Endpoint.
108
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
USBD_EP_CTRL
C learance N o.: FT DI#453
Control Endpoint.
2.21.4.7 USBD_ENDPOINT_DB
enum USBD_ENDPOINT_DB
USB Endpoint Double Buffering Enable.
Enumerator
USBD_DB_OFF
Disabled.
USBD_DB_ON
Enabled.
2.21.5 Structure Documentation
2.21.5.1 USBD_ctx
Struct containing callback functions for the USB upper layer driver and callback functions for USB
suspend/resume and USB reset. Sets USBD configuration information.
Data Fields
USBD_descriptor_callback
get_descriptor_cb
USBD_request_callback
standard_req_cb
USBD_request_callback
class_req_cb
USBD_request_callback
vendor_req_cb
USBD_suspend_callback
suspend_cb
USBD_suspend_callback
resume_cb
USBD_suspend_callback
lpm_cb
USBD_reset_callback
reset_cb
USBD_suspend_callback
sof_cb
USBD_ENDPOINT_SIZE
ep0_size
USBD_ep_callback
ep0_cb
USBD_DEVICE_SPEED
speed
uint8_t
lowPwrSuspend
Field Documentation
class_req_cb
[Optional] class request callback function.
ep0_cb
Callback function for a data transfer to or from the control endpoint.
ep0_size
Endpoint size for control endpoints. Section 3.3.1 FT900 USB Program Manual. Sets
DC_EP0_CONTROL register in Table 3.6.
0: 8 bytes. 1: 16 bytes. 2: 32 bytes. 3: 64 bytes.
109
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
get_descriptor_cb
[Optional] Descriptor callback function.
Handler function to obtain descriptors (device, configuration, string, HID, Hub etc.) for use with
the built-in USB standard request handler. This must be pres ent if the standard request handler
callback is not used.
lowPwrSuspend
Device power control. Engage power saving mode if bus -powered and suspend state entered.
0: Disable. 1: Enabled.
lpm_cb
[Optional] USB bus LPM (Link Power Management) callback function.
reset_cb
[Optional] USB bus reset callback function.
resume_cb
[Optional] USB bus suspend callback function.
sof_cb
[Optional] USB SOF callback function.
speed
Device configuration section. High speed/full speed select. Section 3.2.2 FT900 USB Prog ram
Manual.
0: Full speed only. 1: High speed if available.
standard_req_cb
[Optional] Standard request callback function.
Handler for USB standard requests. This is used for overriding the built-in standard request
handler to customise the responses to s tandard requests. If it is not set then the built-in handler
will be used and the descriptor_cb function used to obtain descriptors.
suspend_cb
[Optional] USB bus suspend callback function.
vendor_req_cb
[Optional] vendor request callback function.
2.21.6 Function Documentation
2.21.6.1 USBD_initialise
void USBD_initialise ( USBD_ctx *
ctx )
Initialise USB hardware.
Performs a software reset and intialises the USB hardware.
The USBD_ctx contains function pointers to the protocol layer handling USB requests. Appropriate
USB requests will be routed to the correct handler, whether that is Standard, Class or Vendor
requests. A device may not need a handler for Vendor or Class requests depending on the device
configuration.
Optional function pointers are also available fo r USB suspend and resume call-backs and bus
110
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
resets issued by the host.
This function MUST be called prior to any further call to the USB functions.
Parameters
[in] ctx USB context.
2.21.6.2 USBD_finalise
void USBD_finalise ( void
)
Finalise USB hardware.
Releases any resources associated with the USB driver and disables the hardware.
2.21.6.3 USBD_attach
void USBD_attach ( void
)
Attach USB hardware.
Attaches the USB device to the USB host after a USBD_detach call.
2.21.6.4 USBD_detach
void USBD_detach ( void
)
Detach USB hardware.
Detaches the USB device from the USB host. This will look like a device disconnect to the host and
it will act like the device is removed.
2.21.6.5 USBD_is_connected
int8_t USBD_is_connected ( )
Check if the device is connected to a host (or external power source).
Checks the VBUS detect line for a host connected.
2.21.6.6 USBD_set_state
void USBD_set_state ( USBD_STATE state )
Set USB state.
Sets the current state of the current USB device. Please refer to section 9.1 of the USB 2.0 spec
for more information.
Parameters
[in] state The new state of the current USB device.
2.21.6.7 USBD_create_endpoint
int8_t USBD_create_endpoint ( USBD_ENDPOINT_NUMBER
ep_number,
USBD_ENDPOINT_TYPE
ep_type,
USBD_ENDPOINT_DIR
ep_dir,
USBD_ENDPOINT_SIZE
ep_size,
USBD_ENDPOINT_DB
ep_db,
111
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
USBD_ep_callback
C learance N o.: FT DI#453
ep_cb
)
Create a USB endpoint.
Creates an endpoint with the requested properties.
There are a total of 2 kB of RAM for IN endpoints and another 2 kB for OUT endpoints (excluding
the RAM allocated to endpoint 0). Therefore the total max packet for all IN endpoints and OUT
endpoints must be less than this figure. If double buffering is employed for an endpoint then it will
use twice the amount of RAM.
Parameters
[in] ep_number USB endpoint number. (N/A for control endpoints).
[in] ep_type
USB endpoint type: BULK, ISO or INT. (N/A for control endpoints).
[in] ep_dir
Endpoint direction, In or Out.
[in] ep_size
USB endpoint max packet size in bytes.
[in] ep_db
USB endpoint double buffering enable. (N/A for control endpoints).
[in] ep_cb
Callback functions for this endpoint. This function will be called from the
USBD_process function when an event concerned with the endpoint has
occurred. This can be used for receiving notification of a transaction to or
from the endpoint heralding the availability of data (OUT endpoints) or
the completion of a transmission of data (IN endpoints). However,
the USBD_ep_buffer_full() function can be polled to determine the
same status if callbacks are inappropriate.
Returns
USBD_OK if successful.
USBD_ERR_NOT_SUPPORTED if an endpoint higher than the maximum number of endpoints is
requested.
USBD_ERR_INVALID_PARAMETER if an illegal endpoint size is requested.
USBD_ERR_RESOURCES if there is not enough endpoint RAM for the endpoint size requested.
2.21.6.8 USBD_free_endpoint
int8_t USBD_free_endpoint ( USBD_ENDPOINT_NUMBER
ep_number )
Free USB endpoint.
Disable and free the specified endpoint.
Parameters
[in] ep USB endpoint handle.
Returns
USBD_OK if successful
USBD_ERR_NOT_CONFIGURED if endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if endpoint number not allowed.
2.21.6.9 USBD_connect
int8_t USBD_connect ( void
)
Connect to a USB host.
Checks the VBUS detect line for a host connected and proceed to allow the device to negotiate a
connection to the host.
112
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
USBD_OK on success.
USBD_ERR_INVALID_PARAMETER if req is invalid.
2.21.6.10
USBD_tim er
void USBD_timer ( void
)
USB timer.
To be called every millisecond from an interrupt handler to provide timeout support for USB device
transactions. This will check all pending transfers, decrement timeout values and expire any timed
out transactions.
2.21.6.11
USBD_process
int8_t USBD_process ( void
)
USB process.
To be continuously called by the user application or USB device thread. Checks for control endpoint
transfer activity and invoke relevant callback. Manages suspend and resume states and power
management.
Returns
Non-zero if USB transaction has been processed.
2.21.6.12
USBD_transfer
int32_t USBD_transfer ( USBD_ENDPOINT_NUMBER
ep_number,
uint8_t *
buffer,
size_t _t
length
)
Transfer data to/from a non-control USB endpoint.
USB IN or OUT request is implied from the settings of the endpoint passed as a paramet er.
Parameters
[in] ep_number USB endpoint number.
[in] buffer
Appropriately sized buffer for the transfer.
[in] length
For IN transfers, the number of bytes to be sent. For OUT transfers, the
maximum number of bytes to read.
Returns
The number of bytes actually transferred.
USBD_ERR_NOT_CONFIGURED if endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if endpoint number not allowed.
2.21.6.13
USBD_transfer_ex
int32_t USBD_transfer_ex ( USBD_ENDPOINT_NUMBER
ep_number,
uint8_t *
buffer,
size_t _t
length,
int8_t
part,
113
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
size_t
C learance N o.: FT DI#453
offset
)
Transfer data to/from a non-control USB endpoint with options.
USB IN or OUT request is implied from the settings of the endpoint passed as a parameter. The
end-of-packet will not be sent when the data from the buffer parameter is sent.
This will allow a follow -on USBD_transfer_ex call to either send more data (with the part
parameter non-zero and a correct offset set) or an end-of-packet with part not set.
This allows a USB data packet to a non-control endpoint to be formed from multiple calls with data
from potentially different places.
Parameters
[in] ep_number USB endpoint number.
[in] buffer
Appropriately sized buffer for the transfer.
[in] length
For IN transfers, the number of bytes to be sent. For OUT transfers, the
maximum number of bytes to read.
[in] part
Signifies that this is a partial transfer.
[in] offset
Offset (within the current packet) from where to continue for subsequent
calls when using partial packets.
Returns
The number of bytes actually transferred.
USBD_ERR_NOT_CONFIGURED if endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if endpoint number not allowed.
2.21.6.14
USBD_transfer_ep0
int32_t USBD_transfer_ep0 ( USBD_ENDPOINT_DIR
dir,
uint8_t *
buffer,
size_t
dataLength,
size_t
requestLength
)
Transfer data to/from a USB control endpoint.
Endpoint number is assumed to be zero.
Parameters
[in] dir
Control endpoint data direction.
[in] buffer
Appropriately sized buffer for the transfer.
[in] dataLength
For IN transfers, the number of bytes to be sent. For OUT transfers,
the maximum number of bytes to read.
[in] requestLength The number of bytes requested by the host in the wLength field of the
SETUP packet.
Returns
The number of bytes actually transferred.
USBD_ERR_NOT_CONFIGURED if endpoint is not configured.
114
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.21.6.15
C learance N o.: FT DI#453
USBD_clear_endpoint
int8_t USBD_clear_endpoint ( USBD_ENDPOINT_NUMBER
ep_number )
Clears endpoint stall.
Clears a stall from the specified endpoint. The default standard request handler will call this
function for a CLEAR_FEATURE endpoint request.
Parameters
[in] ep_number USB endpoint number.
Returns
USBD_OK if successful
USBD_ERR_NOT_CONFIGURED if endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if endpoint number not allowed.
2.21.6.16
USBD_clear_rem ote_wakeup
void USBD_clear_remote_wakeup ( void
)
Clear USB remote wakeup feature status.
2.21.6.17
USBD_ep_m ax_size
uint16_t USBD ep_max_size ( USBD_ENDPOINT_NUMBER
ep_number )
Find Max Packet Size of USB endpoint.
Parameters
[in] ep_number USB endpoint number.
Returns
Return the maximum number of byte s which can be sent or received single USB packets for an
endpoint.
USBD_ERR_NOT_CONFIGURED if the endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if the endpoint number is not allowed.
2.21.6.18
USBD_ep_buffer_full
int8_t USBD_ep_buffer_full ( USBD_ENDPOINT_NUMBER
ep_number )
Get USB endpoint buffer status.
Returns the current buffer status of an endpoint using the SELECT_ENDPOINT call.
Parameters
[in] ep_number USB endpoint number.
Returns
Current state of the endpoint buffer. TRUE if full, FALSE if empty.
2.21.6.19
USBD_get_ep_stalled
int8_t USBD_get_ep_stalled ( USBD_ENDPOINT_NUMBER
ep_number )
Get USB endpoint stall status.
Returns the current stall status of an endpoint using the SELECT_ENDPOINT call.
115
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
[in] ep_number USB endpoint number.
Returns
Current stall state of the endpoint.
>0 if stalled, zero if not stalled.
USBD_ERR_NOT_CONFIGURED if the endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if the endpoint number is not allowed.
2.21.6.20
USBD_stall_endpoint
int8_t USBD_stall_endpoint ( USBD_ENDPOINT_NUMBER
ep_number )
Stall endpoint.
Stalls the specified endpoint. The default standard request handler will call this function for a
SET_FEATURE endpoint request.
Parameters
[in] ep_number USB endpoint number.
Returns
USBD_OK if successful
USBD_ERR_NOT_CONFIGURED if the endpoint is not configured.
USBD_ERR_INVALID_PARAMETER if the endpoint number is not allowed.
2.21.6.21
USBD_get_state
USBD_STATE USBD_get_state ( void
)
Get USB state.
Returns the current state of the current USB device. Please refer to section 9.1 of the USB 2.0
spec for more information.
Returns
Current state of the current USB device.
2.21.6.22
USBD_req_get_configuration
int8_t USBD_req_get_configuration ( void
)
Handles GET_CONFIGURATION request.
Handles the DATA phase of a GET_CONFIGURATION request from the host. The application has to
respond with SETUP ACK or STALL. The default standard request handler will call this function; if
the handler is overridden then the application must call this when this request is received.
Returns
USBD_OK on success.
USBD_ERR_INVALID_PARAMETER if req is invalid.
2.21.6.23
USBD_req_set_address
int8_t USBD_req_set_address ( USB_device_request * req )
Handles SET_ADDRESS request.
Places the device in the ADDRESS state. The application has to respond with SETUP ACK or STALL.
The default standard request handler will call this function; if the handler is overridden then the
application must call this when this request is received.
116
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
[in] req USB request.
Returns
USBD_OK on success.
USBD_ERR_INVALID_PARAMETER if req is invalid.
2.21.6.24
USBD_req_set_configuration
int8_t USBD_req_set_configuration ( USB_device_request * req )
Handles SET_CONFIGURATION request.
Places the device in the CONFIGURED state or puts it back into the ADDRESS state. The
application has to respond with SETUP ACK or STALL. The default standard request handler will call
this function; if the handler is overridden then the application must call this when this request is
received.
Parameters
[in] req USB request.
Returns
USBD_OK on success.
USBD_ERR_INVALID_PARAMETER if req is invalid.
2.21.6.25
USBD_get_rem ote_wakeup
uint8_t USBD_get_remote_wakeup ( void
)
Get USB remote wakeup feature status.
Returns the current feature status of remote wakeup.
Returns
Current remote wakeup feature status. TRUE if enabled, FALSE if not enabled.
2.21.6.26
USBD_set_rem ote_wakeup
void USBD_set_remote_wakeup ( void
)
Set USB remote wakeup feature status.
2.21.6.27
USBD_wakeup
void USBD_wakeup ( void
)
Resume with a USB remote wakeup.
Perform a resume on the USB bus to initiate a remote wakeup when enabled.
117
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.22 DFU Device for USB Device Stack API
The file ft900_usbd_dfu.h contains the definitions for the USB DFU device functions in the
libft900.a library.
API functions for USB Device DFU interfaces. These functions provide functionality required to
communicate with a DFU application through the USB Device interface.
Please consult the Device Firmware Upgrade 1.1 Specification from the USB-IF for details of the
DFU state machine employed in this driver.
2.22.1 API Cross Reference
It utilises the following library APIs:
ft900_gpio.h – General Purpose I/O and Pad Control
ft900_sys.h – Chip Management
ft900_delay.h – Delay
ft900_interrupt.h – Interrupt Management
Additional definitions are taken from:
ft900_usbh_internal.h – Internal-only USB host definitions
ft900_usb.h – General USB definitions
ft900_registers.h – FT900 register definitions
2.22.2 Macro Definition Documentation
2.22.2.1 USBD_DFU_ATTRIBUTES
#define USBD_DFU_ATTRIBUTES
Value:
(USB_DFU_BMATTRIBUTES_CANDNLOAD |
USB_DFU_BMATTRIBUTES_WILLDETACH |
USB_DFU_BMATTRIBUTES_CANUPLOAD)
Sets the default feature support for the DFU library. This will allow firmware uploads (read of
device firmware), downloads (program device firmware) and device detaches (no USB reset needs
to be generated by the host).
2.22.2.2 USBD_DFU_MAX_BLOCK_SIZE
#define USBD_DFU_MAX_BLOCK_SIZE
Value:
256
Sets the maximum size of a download or upload block for the library. The physical addresses
calculated for programs are based on this value.
2.22.2.3 USBD_DFU_TIMEOUT
#define USBD_DFU_TIMEOUT
Value:
0x2000
118
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
The timeout (in milliseconds) used to revert to the appIDLE state after a DFU_DETACH requ est if a
USB reset is not received. This is not applicable when the USB_DFU_BMATTRIBUTES_WILLDETACH
bit is set in the attributes.
2.22.3 Function Documentation
2.22.3.1 USBD_DFU_tim er
uint8_t USBD_DFU_timer ( void
)
Decrements the detach_counter and adjusts state accordingly.
If the state is appDETACH move to dfuIDLE state if we have been in the appDETACH state longer
than the attach timeout specified by the DFU_DETACH request.
NOTE: This is run from INTERRUPT LEVEL as a handler for an ISR.
The bmAttributes value set in the USBD_DFU_ATTRIBUTES determines the actions that are taken
upon a timer event (i.e. may call a detach).
Parameters
attributes - The bmAttributes value set in the DFU functional descriptor. This determines
the actions that are taken upon a reset.
Returns
Zero if timer running, non-zero if timer expired.
2.22.3.2 USBD_DFU_reset
uint8_t USBD_DFU_reset ( void
)
Implementation of USB reset state handler for DFU.
Reset or advance the DFU state machine when a USB reset is encountered. This will change the
state to dfuIDLE if it was in appDETACH state before. It will change to dfuERROR if a download
was in progress. Otherwise it will return to appIDLE.
Return a byte to the host indicating if the next state change of the DFU state machine byte
requires code to be reloaded and run. I.e. a new program needs to be run. The bmAttributes value
set in the USBD_DFU_ATTRIBUTES determines the actions that are taken upon a reset.
Returns
status - non-zero if new program is to be run.
2.22.3.3 USBD_DFU_is_runtim e
uint8_t USBD_DFU_is_runtime ( void
)
Determine current mode of DFU.
Returns
Returns non-zero if the DFU state machine is in runtime mode.
2.22.3.4 USBD_DFU_set_dfum ode
void USBD_DFU_set_dfumode ( void
)
Force a transition into DFU mode. There is no detaching. This is used when the run-time mode is
not used.
119
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.22.3.5 USBD_DFU_class_req_detach
void USBD_DFU_class_req_detach ( uint16_t timeout )
USB class request handler for DFU_DETACH.
Move the state machine to appDETACH state from appIDLE and initialise a timeout within which
time the host should set a USB reset on the bus. An ACK packet is sent on the USB control IN
endpoint to the host to acknowledge successful completion of this request. The bmAttributes value
set in the USBD_DFU_ATTRIBUTES determines the actions that are taken upon a detach.
Parameters
[in] timeout - Number of milliseconds timeout before reverting to appIDLE if no USB reset
is forthcoming from the host.
2.22.3.6 USBD_DFU_class_req_getstate
void USBD_DFU_class_req_getstate ( uint16_t requestLen )
USB class request handler for DFU_GETSTATE.
Return a single byte to the host containing the current DFU state machine byte. The data is written
via the control IN endpoint to the host.
Parameters
requestLen - Number of bytes requested by the host.
2.22.3.7 USBD_DFU_class_req_getstatus
void USBD_DFU_class_req_getstatus ( uint16_t requestLen )
USB class request handler for DFU_GETSTATUS.
Return a structure to the host containing the current DFU state machine and status bytes. These
are used by the application on the host to work out whether any errors have occurred and what
the status of the device is. The structure is written via the control IN endpoint to the host. The
bmAttributes value set in the USBD_DFU_ATTRIBUTES determines the actions that are taken upon
a GET_STATUS.
Parameters
requestLen - Number of bytes requested by the host.
2.22.3.8 USBD_DFU_class_req_download
void USBD_DFU_class_req_download ( uint32_t block,
uint16_t dataLength
)
USB class request handler for DFU_DNLOAD.
Receive blocks of firmware from the host on the control OUT endpoint and program these into the
MTP. If the state machine is in dfuIDLE then move to dfuDNLOAD_IDLE state.
If zero length data is received indicating the end of the firmware then move the state machine to
dfuMANIFEST_WAIT_RESET. If an address or data length error are detected then move to the
dfuERROR state. An ACK packet is sent on the USB control IN endpoint to the host to acknowledge
successful completion of this request. If the bmAttributes value set in the USBD_DFU_ATTRIBUTES
does not support download then this function will have no body.
120
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
[in] address
- starting address of data to program. It is up to the calling program to
make sure this is calculated correctly.
[in] dataLength - Number of bytes to program. This can be between the control endpoint
max packet size and DFU_MAX_BLOCK_SIZE.
2.22.3.9 USBD_DFU_class_req_upload
void USBD_DFU_class_req_upload ( uint32_t block,
uint16_t dataLength
)
USB class request handler for DFU_UPLOAD.
Receive blocks of firmware from the Flash to the control IN endpoint. If the state machine is in
dfuIDLE then move to dfuUPLOAD_IDLE. If an address or data length error are detected then
move to the dfuERROR state. An ACK packet is sent on the USB control IN endpoint to the host to
acknowledge successful completion of this request. If the bmAttributes value set in the
USBD_DFU_ATTRIBUTES does not support upload then this function will have no body.
Parameters
[in] address
- starting address of data to read. It is up to the calling program to make
sure this is calculated correctly.
[in] dataLength - Number of bytes to read. This can be between the control endpoint
max packet size and DFU_MAX_BLOCK_SIZE.
2.22.3.10
USBD_DFU_class_req_clrstatus
void USBD_DFU_class_req_clrstatus ( void
)
USB class request handler for DFU_CLRSTATUS.
Clears an error state for the DFU state machine.
2.22.3.11
USBD_DFU_class_req_abort
void USBD_DFU_class_req_abort ( void
)
USB class request handler for DFU_ABORT.
Aborts transaction and resets the DFU state machine.
2.22.3.12
USBD_DFU_is_wait_reset
uint8_t USBD_DFU_is_wait_reset ( void
)
Determine if DFU waiting to reset.
Returns
Returns non-zero if the DFU state machine is in dfuMANIFEST-WAIT-RESET and is therefore
waiting for a host reset or detach/attach sequence. If the bmAttributes value set in the
USBD_DFU_ATTRIBUTES does support manifestation then this function should not be required.
121
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.23 USB Host Stack API
The file ft900_usbh.h contains the definitions for the USB host functions in the libft900.a library.
This contains USB Host API function definitions, constants and structures which are exposed in the
API.
2.23.1 API Cross Reference
It utilises the following library APIs:
ft900_gpio.h – General Purpose I/O and Pad Control
ft900_sys.h – Chip Management
ft900_delay.h – Delay
ft900_interrupt.h – Interrupt Management
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_registers.h – FT900 register definitions
2.23.2 Macro Definition Documentation
2.23.2.1 Library status v alues.
#define USBH_OK
0x00
Success for USB Host function.
#define USBH_ENUM_NO_CHANGE
1
No change in enumeration. This status does not constitute an error condition.
#define USBH_ENUM_PARTIAL
2
Partial enumeration only. The enumeration process did not have enough resources to comp letely
enumerate all devices on the USB. This may constitute an error.
#define USBH_ERR_RESOURCES
-1
Lack of resources to perform USB Host function.
#define USBH_ERR_USBERR
-2
Host controller completed and reported an error.
#define USBH_ERR_HOST_HALTED
-3
Host controller halted.
#define USBH_ERR_NOT_FOUND
-4
Endpoint, Device or Interface not found.
#define USBH_ERR_REMOVED
-5
Endpoint, Device or Interface removed.
#define USBH_ERR_STALLED
-6
Endpoint stalled.
#define USBH_ERR_TIMEOUT
-8
Endpoint transaction timeout.
122
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
#define USBH_ERR_PARAMETER
C learance N o.: FT DI#453
-15
Request parameter error.
#define USBH_ERR_HALTED
-16
Transaction completed with halted state.
#define USBH_ERR_DATA_BUF
-17
Endpoint data underun or overrun.
#define USBH_ERR_BABBLE
-18
Endpoint data babble detected.
#define USBH_ERR_MISSED_MICROFRAME
-20
Endpoint data missed microframe.
2.23.2.2 Predefined Handles
#define USBH_ROOT_HUB_HANDLE
0
Handle used to access Root hub.
#define USBH_ROOT_HUB_PORT
0
Port used to access Root hub.
#define USBH_HUB_ALL_PORTS
0
Port used to access all devices on a hub.
2.23.3 Typedef Documentation
2.23.3.1 USBH_callback
typedef int8_t(*
USBH_callback) (uint32_t id, int8_t status, uint16_t len, uint8_t
*buffer)
USB callback used when completing a transaction o r receiving a notification from the USBH library.
It is not permissible to make a call to USBH_transfer_async() and specify a callback function.
This will produce unspecified results.
Parameters
[in] id
Identifier for completed transaction
[in] status Status of operation that caused callback
[in] len
Size of data buffer
[in] buffer Pointer to data buffer
Returns
USBH_OK if the request was handled successfully.
USBH_ERR_* depending on function.
2.23.3.2 Dev ice, Endpoint and Interface Handles
Handles are used to pass devices, interfaces and endpoints to the application. (Pointers to the
USBH_device, USBH_interface and USBH_endpoint structures are not allowed as these are only
123
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
used internally.) The handles allow embedding an enumeration value to detect stale handle s which
have been retained by the application. Enumeration is a dynamic operation and devices may
appear and disappear without warning. This makes sure that new devices cannot be mistakenly
used by an old handle.
typedef uint32_t
USBH_device_handle
Structure that is used to pass a handle to a device to the application. It is made up of a pointer to
the device structure and a fairly unique value to detect enumeration changes and hence stale
handles.
typedef uint32_t
USBH_endpoint_handle
Structure that is used to pass a handle to an endpoint to the application. It is made up of a pointer
to the endpoint structure and a fairly unique value to detect enumeration changes and hence stale
handles.
typedef uint32_t
USBH_ interface _handle
Structure that is used to pass a handle to an interface to the application. It is made up of a pointer
to the interface structure and a fairly unique value to detect enumeration changes and hence stale
handles.
2.23.3.3 Endpoint Inform ation
typedef uint8_t
USBH_ENDPOINT_NUMBER
USB Endpoint Numbers.
typedef uint16_t
USBH_ENDPOINT_SIZE
USB Endpoint Sizes.
2.23.4 Structure Documentation
2.23.4.1 USBH_ctx
Struct containing configuration data for the USB EHCI controller, USBH memory space allocation,
callback functions for USB events.
Data Fields
USBH_callback
enumeration_change
Field Documentation
enumeration_change
NOT CURRENTLY IMPLEMENTED. Enumeration state callback function. Optional. TBD: return a code
and maybe a structure to indicate what has changed and how.
2.23.4.2 USBH_dev ice_info
Structure containing current information about a device .
Data Fields
uint8_t
port_number
uint8_t
addr
uint8_t
speed
uint8_t
configuration
uint8_t
num_configurations
124
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Field Documentation
addr
Configured address on USB bus.
configuration
Active configuration for this device currently set with SET_CONFIGURATION.
num_configurations
Total number of configurations for this device.
port_number
Port number on parent hub.
speed
Current USB bus speed for device. Definitions in USBH_ENDPOINT_SPEED. 0 - Low speed. 1 - Full
speed. 2 - High speed.
2.23.4.3 USBH_interface_info
Structure containing current information about an interface.
Data Fields
USBH_device_handle
dev
uint8_t
interface_number
uint8_t
alt
Field Documentation
alt
Alternate setting for this interface currently set with SET_INTERFACE.
dev
Handle to the parent device of this interface.
interface_number
Interface number from Interface Descriptor.
2.23.4.4 USBH_endpoint_info
Structure containing current information about an endpoint.
Data Fields
USBH_interface_handle
iface
USBH_ENDPOINT_NUMBER
index
USBH_ENDPOINT_DIR
direction
USBH_ENDPOINT_SIZE
max_packet_size
USBH_ENDPOINT_TYPE
type
125
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Field Documentation
direction
IN or OUT endpoint
iface
Handle to the parent interface of this endpoint.
index
Encodes USB endpoint number (0-127).
max_packet_size
Endpoint max packet size
type
BULK, ISO, INT or CTRL endpoint
2.23.5 Enumeration Type Documentation
2.23.5.1 USBH_STATE
enum USBH_STATE
USB Root Hub Connection States.
Enumerator
USBH_STATE_NOTCONNECTED
No device is attached to USB root hub.
USBH_STATE_CONNECTED
Device is attached to USB root hub.
USBH_STATE_ENUMERATED
Device is attached successfully and enumerated. All
downstream devices have also been successfully
enumerated.
USBH_STATE_ENUMERATED_PARTIAL
Device is attached and has been partially enumerated.
There may be more devices, interfaces or endpoints
connected than configured. Some devices may be
missing interfaces and/or endpoints. It is conceivable
that some downstream devices may not be configured at
all.
2.23.5.2 USBH_CONTROLLER_STATE
enum USBH_CONTROLLER_STATE
USB Host Controller State describing if the host is operational or suspending or resuming. Used to
control transitions between these states.
Enumerator
USBH_CONTROLLER_STATE_RESET
Controller reset and uninitialized.
USBH_CONTROLLER_STATE_OPERATIONAL
Controller initialised and operational.
USBH_CONTROLLER_STATE_SUSPENDING
Controller performing a suspend. Transitioning from
126
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
operational to suspend.
USBH_CONTROLLER_STATE_SUSPEND
Controller in suspend state. No SOFs generated.
USBH_CONTROLLER_STATE_RESUME
Controller performing a resume. Transitioning from
suspend to operational.
2.23.5.3 USBH_ENDPOINT_DIR
enum USBH_ENDPOINT_DIR
USB Endpoint Direction.
Enumerator
USBH_DIR_OUT
Direction host to device.
USBH_DIR_IN
Direction device to host.
USBH_DIR_SETUP
Force a SETUP PID to a control endpoint.
2.23.5.4 USBH_ENDPOINT_SPEED
enum USBH_ENDPOINT_SPEED
USB Endpoint Speed.
Enumerator
USBH_SPEED_LOW
Low speed.
USBH_SPEED_FULL
Full speed.
USBH_SPEED_HIGH
High speed.
2.23.5.5 USBH_ENDPOINT_TYPE
enum USBH_ENDPOINT_TYPE
USB Endpoint Types.
Enumerator
USBH_EP_TYPE_DISABLED
Disabled.
USBH_EP_BULK
Bulk Endpoint.
USBH_EP_INT
Interrupt Endpoint.
USBH_EP_ISOC
Isochronous Endpoint.
USBH_EP_CTRL
Control Endpoint.
127
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.23.6 Function Documentation
2.23.6.1 USBH_initialise
void USBH_initialise ( USBH_ctx *
ctx )
Initialise USB hardware.
Performs a software reset and initialises the USB hardware.
The USBH_ctx contains function pointers to the application for handling USB events. Currently only
and enumeration change event is implemented. This function MUST be called prior to any further
call to the USB functions.
Parameters
[in] ctx USB context.
2.23.6.2 USBH_finalise
void USBH_finalise ( void
)
Finalise USB hardware.
Releases any resources associated with the USB driver and disables the hardware.
2.23.6.3 USBH_enum erate
int8_t USBH_enumerate ( USBH_device_handle hub,
uint8_t
port
)
Force a re-enumeration of a hub.
Select a hub to force re-enumeration. To enumerate the root hub the handle is set to
USBH_ROOT_HUB_HANDLE or zero. To enumerate all ports on a hub set the port value to
USBH_HUB_ALL_PORTS or zero.
NOTE: The USBH_process call will monitor the Root hub and downstream hubs to manage the
connection/removal of devices and enumeration of devices.
Parameters
[in] hub Handle to hub device.
[in] port Port on hub.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.4 USBH_process
int8_t USBH_process ( void
)
To be continuously called by the user application. Checks for asynchronous transfer completions
and root hub events.
When a root hub connection is detected then the enumeration routine is called automatically.
There is no requirement to call USBH_enumerate if USBH_process is called periodically.
128
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
[in] Nothing
Returns
Non-zero if USB transaction has been processed.
2.23.6.5 USBH_tim er
void USBH_timer ( void
)
To be called every millisecond from an interrupt handler to provide timeout support for USB host
transactions. This will check all pending transfers, decrement timeout values and expire any timed
out transactions.
2.23.6.6 USBH_transfer
int32_t USBH_transfer ( USBH_endpoint_handle
endpoint,
uint8_t *
buffer,
size_t
length,
uint16_t
timeout
)
Transfer data to/from a USB endpoint.
USB IN or OUT request is implied from the ep parameter. This is a blocking call to complete a
transaction.
Parameters
[in] endpoint Endpoint to address.
[in] buffer
Appropriately sized buffer for the transfer.
[in] length
For IN transfers, the number of bytes to be sent. For OUT transfers, the
maximum number of bytes to read.
[in] timeout Number of milliseconds to wait for response.
Returns
Number of bytes transferred if successful. (i.e. >= 0)
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.7 USBH_transfer_async
int32_t USBH_transfer_async ( USBH_endpoint_handle endpoint,
uint8_t *
buffer,
size_t
length,
uint16_t
timeout,
uint32_t
id,
USBH_callback
cb
)
129
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Asynchronously transfer data to/from a USB endpoint.
USB IN or OUT request is implied from the ep parameter. This is a blocking call to complete a
transaction.
Parameters
[in] endpoint Endpoint to address.
[in] buffer
Appropriately sized buffer for the transfer.
[in] length
For IN transfers, the number of bytes to be sent. For OUT transfers, the
maximum number of bytes to read.
[in] timeout Number of milliseconds to wait for response. Zero for infinite timeout.
[in] id
Identifier for asynchronous transaction. Passed to the callback function.
[in] cb
Callback function to notify application of completion of asynchronous
transfer. Parameters for callback function are defined in the USBH_callback
typedef. The status of the transaction and any pending data (from an IN)
will be returned to the callback function. The function must return with
minimum processing. When it returns the USB_xfer structure is discarded
and invalidated. It is not permissible to make further calls to this function
from with the callback function.This will produce unspecified results. SETUP
and blocking calls are allowed but may have a performance penalty on
application code.
Returns
Number of bytes transferred if successful. (i.e. >= 0)
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.8 USBH_get_connect_state
int8_t USBH_get_connect_state ( USBH_device_handle
hub,
uint8_t
port,
USBH_STATE *
state
)
Determine if a hub port has a downstream connection.
Select a hub and a port to query. For the root hub the handle will be NULL and the port zero.
Parameters
[in]
hub
Handle to hub device.
[in]
port Port number on hub.
[out] state USBH_STATE enumeration for current state of hub port connection.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_* an error occurred sending the request to a USB hub.
2.23.6.9 USBH_get_controller_state
int8_t USBH_get_controller_state ( USBH_CONTROLLER_STATE * state )
130
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Get host controller state.
Get the state of the host controller. This may be used by an application to check if the controller is
in suspend or operational state. There are intermediate states which can be found during
transitions from operational to suspend and back. Recommended to use explicit state tests, i.e. "if
state is suspended" rather than "if state is not operational".
Parameters
[out] state State enum for host.
Returns
USBH_OK if successful.
2.23.6.10
USBH_get_fram e_number
uint16_t USBH_get_frame_number ( void
)
Get frame number.
Get the current frame number. These increments when the host is operational and will cease to
increment when suspended. This number is sent in the SOF.
Returns
Frame number (14 bit value).
2.23.6.11
USBH_get_dev ice_count
int8_t USBH_get_device_count ( USBH_device_handle
uint8_t *
device,
count
)
Get device count.
Get the count of child device enumerated for a device. For devices on the root hub the handle is
set to USBH_ROOT_HUB_HANDLE.
Parameters
[in]
device Count child devices on this device
[out] count Number of child devices
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.12
USBH_get_dev ice_list
int8_t USBH_get_device_list ( USBH_device_handle
device,
USBH_device_handle * child
)
Get device list.
Get the first child device of a device. The function will return a handle to a device if there are one
or more child devices. For devices on the root hub the handle is set to USBH_ROOT_HUB_HANDLE.
If there are no interfaces then a NULL is returned.
Parameters
131
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
[in]
C learance N o.: FT DI#453
device Handle to a device.
[out] child
Handle to first child device.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.13
USBH_get_next_dev ice
int8_t USBH_get_next_device ( USBH_device_handle
device,
USBH_device_handle * next
)
Get next device in list.
Get the next device in the list. The function will return a handle to the device if there are more
devices. If there are no more devices then a NULL is returned.
Parameters
[in] device Handle to a device.
[in] device Handle to a device.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.14
USBH_dev ice_get_info
int8_t USBH_device_get_info ( USBH_device_handle
device,
USBH_device_info * info
)
Get device information.
Get information of a device.
Parameters
[in]
device Handle to a device.
[out] info
Structure to receive device information.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.15
USBH_dev ice_get_descriptor
int8_t USBH_device_get_descriptor ( USBH_device_handle
device,
uint8_t
type,
uint8_t
index,
uint16_t
len,
uint8_t *
buf
132
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
)
Get a descriptor from a device.
Sends a GET_DESCRIPTOR request to a device.
Parameters
[in] device Handle to a device.
[in] type
Configuration descriptor type.
[in] index Index of descriptor.
[in] len
Configuration descriptor len (or number of bytes to read).
[in] buf
Location to copy descriptor into.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus e rrors.
2.23.6.16
USBH_dev ice_get_configuration
int8_t USBH_device_get_configuration ( USBH_device_handle device,
uint8_t *
conf
)
Gets the current configuration value of a device.
Sends a GET_CONFIGURATION request to a device.
Parameters
[in]
device Handle to a device.
[out] conf
Current configuration value.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.17
USBH_dev ice_get_v id_pid
int8_t USBH_device_get_vid_pid ( USBH_device_handle
device,
uint16_t *
vid,
uint16_t *
pid
)
Get device VID and PID.
Get the VID and PID of a device.
Parameters
[in]
device Handle to a device.
133
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
[out] vid
Vendor ID value from Device Descriptor.
[out] pid
Product ID value from Device Descriptor.
C learance N o.: FT DI#453
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.18
USBH_dev ice_setup_transfer
int32_t USBH_device_setup_transfer ( USBH_device_handle
device,
USB_device_request * req,
uint8_t *
buffer,
int16_t
timeout
)
Transfer data to/from a USB control endpoint.
USB IN or OUT request is implied from the req parameter. The length of the transfer is implied
from the dwLength member of the USB_device_request structure. For IN transfers, length is the
number of bytes to be sent. For OUT transfers, length is the maximum number of bytes to read.
Parameters
[in] device
Device to address.
[in] req
USB Device Request to send in SETUP token.
[in] buffer
Appropriately sized buffer for the transfer.
[in] timeout Number of milliseconds to wait for response.
Returns
Number of bytes transferred if successful. (i.e. >= 0)
USBH_ERR_NOT_FOUND if device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.19
USBH_dev ice_rem ote_wakeup
int8_t USBH_device_remote_wakeup ( USBH_device_handle
const uint8_t
device,
request
)
Sets or clears a remote wakeup feature request to a device.
Sends a SET_FEATURE request to a device.
This function is currently NOT IMPLEMENTED.
Parameters
[in] device Handle to a device.
[in] request Set or Clear Port feature. Described in Table 9-4 in Section 9.4 of USB
Specification.
Returns
134
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.20
USBH_dev ice_set_configuration
int8_t USBH_device_set_configuration ( USBH_device_handle device,
const uint8_t
conf
)
Sets the current configuration value of a device.
Sends a SET_CONFIGURATION request to a device.
NOTE: Should strictly only be done during enumeration.
Parameters
[in] device Handle to a device.
[in] conf
New configuration value.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if the device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.21
USBH_get_interface_count
int8_t USBH_get_interface_count ( USBH_device_handle device,
uint8_t *
count
)
Get interface count.
Get the count of interfaces enumerated for a device.
Parameters
[in]
device Count interface on this device
[out] count Number of interfaces on device
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if the device handle is invalid.
2.23.6.22
USBH_get_interface_list
int8_t USBH_get_interface_list ( USBH_device_handle
device,
USBH_interface_handle * interface
)
Get interface list.
Get the first interface of a device. The function will return a handle to the interface if there is one
or more interfaces. If there are no interfaces then a NULL is returned.
135
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
[in]
device
Handle to a device.
[out] interface Handle to the first interface.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.23
USBH_get_next_interface
int8_t USBH_get_next_interface ( USBH_interface_handle
interface,
USBH_interface_handle * next
)
Get next interface in list.
Get the next interface in the list. The function will return a handle to the in terface if there are more
interfaces. If there are no more interfaces then a NULL is returned.
Parameters
[in]
interface Handle to an interface.
[out] next
Handle to the next interface.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
2.23.6.24
USBH_interface_get_info
int8_t USBH_interface_get_info ( USBH_interface_handle
USBH_interface_info *
interface,
info
)
Get interface information.
Get information of an interface.
Parameters
[in]
interface Handle to an interface.
[out] info
Structure to receive interface information.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
2.23.6.25
USBH_interface_get_class_info
int8_t USBH_interface_get_class_info ( USBH_interface_handle
interface,
uint8_t *
devClass,
uint8_t *
devSubclass,
uint8_t *
devProtocol
136
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
)
Get interface class, subclass and protocol.
Get the class information of an interface.
Parameters
[in]
interface
[out] devClass
Handle to an interface.
USB class value for the interface.
[out] devSubclass USB subclass value for the interface.
[out] devProtocol USB protocol value for the interface.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
2.23.6.26
USBH_get_control_endpoint
int8_t USBH_get_control_endpoint ( USBH_device_handle
device,
USBH_endpoint_handle * endpoint
)
Get control endpoint.
Get the control endpoint of a device. The function will return a handle to the control endpoint.
Parameters
[in]
device
Handle to a device.
[out] endpoint Handle to a control endpoint.
Returns
USBH_OK if successful. USBH_ERR_NOT_FOUND if device handle is invalid.
2.23.6.27
USBH_get_endpoint_count
int8_t USBH_get_endpoint_count ( USBH_interface_handle
uint8_t *
interface,
count
)
Get endpoint count.
Get the count of endpoints enumerated for an interface.
Parameters
[in]
interface Count endpoints on this interface
[out] count
Number of endpoints on interface
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
137
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.23.6.28
C learance N o.: FT DI#453
USBH_get_endpoint_list
int8_t USBH_get_endpoint_list ( USBH_interface_handle
interface,
USBH_endpoint_handle * endpoint
)
Get endpoint list.
Get the first endpoint of an interface. The function will return a handle to the endpoint if there are
one or more endpoints. If there are no endpoints then a NULL is returned.
Parameters
[in]
interface Handle to an interface.
[out] next
Handle to first endpoint.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
2.23.6.29
USBH_get_next_endpoint
int8_t USBH_get_next_endpoint ( USBH_endpoint_handle
endpoint,
USBH_endpoint_handle * next
)
Get next endpoint in list.
Get the next endpoint in the list. The function will return a handle to the endpoint if there are more
endpoints. If there are no more endpoints then a NULL is returned.
Parameters
[in]
endpoint Handle to an endpoint.
[out] next
Handle to next endpoint.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
2.23.6.30
USBH_endpoint_get_info
int8_t USBH_endpoint_get_info ( USBH_endpoint_handle
endpoint,
USBH_endpoint_info * info
)
Get endpoint information.
Get information of an endpoint.
Parameters
[in]
endpoint Handle to an endpoint.
[out] info
Structure to receive endpoint information.
138
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
2.23.6.31
USBH_endpoint_halt
int8_t USBH_endpoint_halt ( USBH_endpoint_handle
const uint8_t
endpoint,
request
)
Sets or clears an endpoint halt feature request to an endpoint.
Sends a SET_FEATURE request to an endpoint.
Parameters
[in] endpoint Handle to an endpoint.
[in] request Set or Clear Port feature. Described in Table 9-4 in Section 9.4 of USB
Specification.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.23.6.32
USBH_interface_clear_host_halt
int8_t USBH_interface_clear_host_halt ( USBH_endpoint_handle
endpoint )
Clear a halted flag on an endpoint in the host controller.
Instruct the USB host controller to remove the halt flag from an endpoint.
Parameters
[in] endpoint Handle to an endpoint.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if endpoint handle is invalid.
2.23.6.33
USBH_get_hub_status
int8_t USBH_get_hub_status ( USBH_device_handle hub,
USB_hub_status *
status
)
Return status specified hub.
For the hub pointed to by the handle, return the status of the hub. For the root hub the handle will
be NULL.
Parameters
[in]
hub
Handle to hub device.
[out] status Hub status. As described in Table 11-19 and Table 11-20 of Section 11.24.2.6
in the USB Specification. Status in low word and change in high word.
139
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
USBH_OK on success.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_* an error occurred querying a USB hub.
2.23.6.34
USBH_get_hub_port_count
int8_t USBH_get_hub_port_count ( USBH_device_handle
uint8_t *
hub,
count
)
Return number of ports on specified hub.
For the hub pointed to by the handle, return the number of p orts that are available. For the root
hub the handle will be NULL.
Parameters
[in]
hub
Handle to hub device.
[out] count Number of ports on hub.
Returns
USBH_OK on success.
USBH_ERR_NOT_FOUND if hub handle is invalid.
2.23.6.35
USBH_get_hub_port_status
int8_t USBH_get_hub_port_status ( USBH_device_handle
const uint8_t
hub,
port,
USB_hub_port_status * status
)
Return the status of the specified port on the hub.
For the hub pointed to by the handle, return the status of the numbered port. For the root hub the
handle will be NULL.
Parameters
[in]
hub
Handle to hub device.
[in]
port
Port number on hub.
[out] status Port status. As described in Table 11-21 of Section 11.24.2.7 in the USB
Specification.
Returns
USBH_OK on success.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_* an error occurred querying a USB hub.
140
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.23.6.36
C learance N o.: FT DI#453
USBH_hub_set/clear_feature
int8_t USBH_hub_clear_feature ( USBH_device_handle
hub,
const uint16_t
feature
)
int8_t USBH_hub_set_feature ( USBH_device_handle
const uint16_t
hub,
feature
)
Set/Clear Features on hub.
For the hub pointed to by the handle, send a set or clear feature. For the root hub the handle will
be NULL. Set or Clear feature operation described in Section 11.24.2.12 & 11.24.2.1 of the USB
Specification.
Parameters
[in] hub
Handle to hub device.
[in] feature Port feature. As described in Table 11-17 of Section 11.24.2 in the USB
Specification.
Returns
USBH_OK on success.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_* an error occurred se nding the request to a USB hub.
2.23.6.37
USBH_hub_set/clear_port_feature
int8_t USBH_hub_set_port_feature
( USBH_device_handle
hub,
const uint8_t
port,
const uint16_t
feature
)
int8_t USBH_hub_clear_port_feature ( USBH_device_handle
hub,
const uint8_t
port,
const uint16_t
feature
)
Set/Clear Port Features on hub.
For the hub pointed to by the handle, send a set or clear port feature. For the root hub the handle
will be NULL. Set or Clear Port feature operation described in Section 11.2 4.2.13 & 11.24.2.2 of
the USB Specification.
Parameters
[in] hub
Handle to hub device.
[in] port
Port number on hub.
[in] feature Port feature. As described in Table 11-17 of Section 11.24.2 in the USB
141
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Specification.
Returns
USBH_OK on success.
USBH_ERR_NOT_FOUND if hub handle is invalid.
USBH_ERR_* an error occurred sending the request to a USB hub.
142
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.24 USB Host Stack Extensions API
The file ft900_usbd.h contains the definitions for the USB host extension functions in the
libft900.a library.
API functions for extensions to the USB Host stack. These functions provide additional
functionality useful to implement a USB Host application.
2.24.1 API Cross Reference
It utilises the following library APIs:
ft900_usbh.h – USB host
Additional definitions are taken from:
ft900_usb.h – General USB definitions
2.24.2 Function Documentation
2.24.2.1 USBHX_enum erate_wait
USBH_STATE USBHX_enumerate_wait ( void
)
Waits for a connection to the root hub and enumerates the device.
Will block until a device is connected to the root hub and then proceed to enumerate it and any
downstream devices. Once this is complete then it will check the enumeration result and return.
Will never return USBH_STATE_NOTCONNECTED.
Returns
USBH_STATE_CONNECTED - a device is connected but there was a general failure to enumerate.
USBH_STATE_ENUMERATED - Device connected and enumerated properly.
USBH_STATE_ENUMERATED_PARTIAL - Device connected and enumeration started. Enumeration
did not complete so some devices, interfaces or endpoints may be missing.
2.24.2.2 USBHX_find_by _class
int8_t USBHX_find_by_class ( USBH_device_handle *
phDev,
USBH_interface_handle * phInterface,
uint8_t
usbClass,
uint8_t
usbSubclass,
uint8_t
usbProtocol
)
Get interface class, subclass and protocol.
Get the class information of an interface.
Parameters
[in] interface Handle to an interface.
[out] class
USB class value for interface.
[out] subclass USB subclass value for interface.
[out] protocol USB protocol value for interface.
143
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if interface handle is invalid.
2.24.2.3 USBHX_find_by_v id_pid
int8_t USBHX_find_by_vid_pid ( USBH_device_handle * phDev,
uint16_t
usbVid,
uint16_t
usbPid
)
Find the first device with a specific VID and PID.
Get the VID and PID of a device.
Parameters
[in] device Handle to a device.
[out] vid
Vendor ID value from Device Descriptor.
[out] pid
Product ID value from Device Descriptor.
Returns
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
2.24.2.4 USBHX_get_config_descriptor
int8_t USBHX_get_config_descriptor ( USBH_device_handle
device,
uint8_t
type,
uint8_t
index,
uint16_t
offset,
uint16_t
len,
uint8_t *
buf
)
Get a partial descriptor from a device.
Sends a GET_DESCRIPTOR request to a device and returns a section of the data.
Parameters
[in] device Handle to a device.
[in] type
Configuration descriptor type.
[in] index Index of descriptor.
[in] offset Start position in descriptor to read.
[in] len
Number of bytes to read from position "offset".
[in] buf
Location to copy descriptor into (must be minimum size of "len").
Returns
144
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
USBH_OK if successful.
USBH_ERR_NOT_FOUND if device handle is invalid.
USBH_ERR_RESOURCES if there are insufficient resources.
USBH_ERR_* depending on USB bus errors.
2.24.2.5 USBHX_root_connected
int8_t USBHX_root_connected ( void
)
Tests if a device is connected to the root hub.
Returns
zero - No device connected.
non-zero - A device is connected but may not be enumerated.
2.24.2.6 USBHX_root_enum erated
int8_t USBHX_root_enumerated ( void
)
Tests if a device is connected to the root hub and enumerated.
Returns
zero - No device enumerated.
non-zero - A device is connected and enumerated. The device can be used with the USBH driver.
2.24.2.7 USBHX_root_enum eration_failed
int8_t USBHX_root_enumeration_failed ( void
)
Tests if the enumeration worked correctly.
Returns
zero - Device(s) enumerated correctly.
non-zero - No device connected, a device is connected but not enumerated or the device may have
not been enumerated completely.
145
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.25 HID Devices on USB Host Stack API
The file ft900_usbh_hid.h contains the definitions for the USB host HID functions in the
libft900.a library.
API functions for USB Host HID devices. These functions provide functionality required to
communicate with a HID device through the USB Host interface.
Please refer to the documentation produced by the USB-IF covering HID devices including the
Device Class Definition for HID 1.11.
2.25.1 API Cross Reference
It utilises the following library APIs:
ft900_delay.h – Delay
ft900_usbh.h – USB host
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_usb_hid.h –USB HID definitions
2.25.2 Structure Documentation
2.25.2.1 USBH_HID_context
HID device context.
Holds a context structure required by each instance of the driver.
Data Fields
USBH_device_handle
hHIDDevice
USBH_interface_handle
hHIDInterface
uint8_t
hidInterfaceNumber
USBH_endpoint_handle
hHIDEpIn
USBH_endpoint_handle
hHIDEpOut
uint8_t
reportInSize
uint8_t
reportOutSize
Field Documentation
hHIDDevice
USB host device handle for HID device.
hHIDInterface
USB host interface handle for HID device.
hidInterfaceNumber
Interface number for HID device.
hHIDEpIn
Handle for IN endpoint used by HID device.
hHIDEpOut
Handle for OUT endpoint used by HID device.
146
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
reportInSize
Report size in bytes for IN reports.
reportOutSize
Report size in bytes for OUT reports.
2.25.3 Function Documentation
2.25.3.1 USBH_HID_init
int8_t USBH_HID_init ( USBH_device_handle
hHIDDev,
USBH_interface_handle
hHIDInterface,
USBH_HID_context *
ctx
)
Initialise HID device.
Initialises the instance of the HID device and stores information in
the USBH_HID_context structure passed from the application. This allows individual instances of
the HID device to be accessed independently.
Parameters
[in]
hHIDDev
[in]
hHIDInterface Handle of interface on hHIDDev to use for driver. There may be
more than one HID interface on a device.
[out] ctx
Handle of HID device on USB bus.
Pointer to HID context.
Returns
Zero if successful, non-zero if not.
2.25.3.2 USBH_HID_get_report_size_in
int8_t USBH_HID_get_report_size_in ( USBH_HID_context * ctx )
Gets the IN report size for the HID device.
Allows the application to discover the size of reports sent by the HID device.
Parameters
[in] ctx Pointer to HID context.
Returns
Zero if fail, non-zero for report size.
2.25.3.3 USBH_HID_get_report_size_out
int8_t USBH_HID_get_report_size_out ( USBH_HID_context * ctx )
Gets the OUT report size for the HID device.
Allows the application to discover the size of reports to send to the HID device.
Parameters
[in] ctx Pointer to HID context.
147
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
Zero if fail, non-zero for report size.
2.25.3.4 USBH_HID_set_idle
int8_t USBH_HID_set_idle ( USBH_HID_context * ctx,
uint16_t
idle
)
Send a SET IDLE request to the HID device.
Forms and sends a SET IDLE request to the control endpoint of the HID device. The interface
number of the HID interface is included to tell the device which of possible multiple interfaces to
idle.
Parameters
[in] ctx Pointer to HID context.
[in] idle Timeout for idle, zero is infinite.
Returns
Zero if successful, non-zero if not.
2.25.3.5 USBH_HID_get_report
int8_t USBH_HID_get_report ( USBH_HID_context * ctx,
uint8_t *
buffer
)
Gets an IN report from the HID device.
Returns a report from the device's IN endpo int into the buffer pointed to in the parameters. The
buffer must be large enough for the number of bytes returned
in USBH_HID_get_report_size_in()
Parameters
[in]
ctx
Pointer to HID context.
[out] buffer Buffer to receive data.
Returns
Zero if successful, non-zero if not.
148
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.25.3.6 USBH_HID_set_report
int8_t USBH_HID_set_report ( USBH_HID_context * ctx,
uint8_t *
buffer
)
Sends an OUT report to the HID device.
Transmits a report to the device's OUT endpoint from the buffer pointed to in the parameters. The
buffer must contain at least the number of bytes returned
in USBH_HID_get_report_size_out()
Parameters
[in]
ctx
Pointer to HID context.
[out] buffer Buffer providing data.
Returns
Zero if successful, non-zero if not.
149
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.26 BOMS Devices on USB Host Stack API
The file ft900_usbh_boms.h contains the definitions for the USB host BOMS functions in the
libft900.a library.
API functions for USB Host BOMS devices. These functions provide functionality required to
communicate with a BOMS device through the USB Hos t interface.
Please refer to the documentation produced by the USB-IF covering BOMS devices including the
Mass Storage Bulk Only 1.0 specification.
2.26.1 API Cross Reference
It utilises the following library APIs:
ft900_delay.h – Delay
ft900_usbh.h – USB host
ft900_usbhx.h – USB host extensions
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_usb_boms.h –USB BOMS definitions
2.26.2 Macro Definition Documentation
2.26.2.1 Block Size
#define USBH_BOMS_BLOCK_SIZE
512
Defines the size of a sector on the BOMS device used by this library. This can be 512 bytes or 2 kB
according to the Bulk Only Mass Storage specification. Only 512 byte sectors have been tested.
2.26.2.2 Library Return Codes
#define USBH_BOMS_OK
0
Success for BOMS function.
#define USBH_BOMS_ERR_PARAMETER
-1
Parameter error in call to BOMS function.
#define USBH_BOMS_ERR_CLASS_NOT_SUPPORTED
-2
Device class not supported.
#define USBH_BOMS_ERR_SCSI
-3
USB error received during SCSI commands.
#define USBH_BOMS_ERR_STATUS
-5
Error received during status phase.
#define USBH_BOMS_ERR_CLASS
-6
BOMS class error during function.
#define USBH_BOMS_ERR_LUN
-7
Requested LUN is not available.
#define USBH_BOMS_ERR_CAPACITY_TIMEOUT
-8
150
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
SCSI Get Capacity request timed out.
2.26.3 Structure Documentation
2.26.3.1 USBH_BOMS_context
BOMS device context.
Holds a context structure required by each instance of the driver.
Data Fields
USBH_device_handle
hBomsDevice
USBH_interface_handle
hBomsInterface
uint8_t
bomsInterfaceNumber
USBH_endpoint_handle
hBomsEpIn
USBH_endpoint_handle
hBomsEpOut
uint8_t
maxLun
uint8_t
lun
uint32_t
lba_count
uint16_t
lba_size
uint16_t
vid
uint16_t
pid
uint8_t
vendorId [8]
uint8_t
productId [16]
uint8_t
rev [4]
uint32_t
tag
Field Documentation
hBomsDevice
USB host device handle for BOMS device.
hBomsInterface
USB host interface handle for BOMS device.
bomsInterfaceNumber
Interface number for BOMS device.
hBomsEpIn
Handle for IN endpoint used by BOMS device.
hBomsEpOut
Handle for OUT endpoint used by BOMS device.
maxLun
Maximum LUN supported on this BOMS device .
lun
151
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Current LUN in use.
lba_count
Logical block count (number of sectors on device).
lba_size
Size of logical blocks (sector size).
vid
VID of BOMS device.
pid
PID of BOMS device.
vendorId
String containing Vendor Name of BOMS device (may not be NULL terminated).
productId
String containing Product Name of BOMS device (may not be NULL terminated).
rev
Device specific revision information.
tag
Library Internal Use Tag.
2.26.4 Function Documentation
2.26.4.1 USBH_BOMS_init
int8_t USBH_BOMS_init ( USBH_interface_handle
hBomsInterface,
uint8_t
lun,
USBH_BOMS_context *
ctx
)
Initialise the BOMS driver.
Setup a context for the BOMS driver to use the interfaces and settings provided in t he call.
Parameters
hBomsInterface - handle to the BOMS interface.
lun
- Logical Unit Number on device to use.
ctx
- Structure instantiated in the application to hold the context information
for this instance of the driver.
Returns
USBH_BOMS_OK if successful
152
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.26.4.2 USBH_BOMS_get_m ax_lun
int8_t USBH_BOMS_get_max_lun ( USBH_BOMS_context * ctx,
uint8_t *
maxLun
)
Gets the number of LUNs on the BOMS device.
Queries the device to find the number of Logical Units on the device.
Parameters
ctx
- Driver context.
maxLun - The number of the highest numbered LUN on the device.
Returns
USBH_BOMS_OK if successful
2.26.4.3 USBH_BOMS_reset
int8_t USBH_BOMS_reset ( USBH_BOMS_context * ctx )
Reset the BOMS device.
Performs a BOMS device reset operation.
Parameters
ctx - Driver context.
Returns
USBH_BOMS_OK if successful
2.26.4.4 USBH_BOMS_read
int8_t USBH_BOMS_read ( USBH_BOMS_context * ctx,
uint32_t
lba,
uint32_t
len,
uint8_t *
buffer
)
Read sectors from the BOMS device.
Read one or more sectors from the device. This blocks until the required amount of data is read.
Parameters
ctx
- Driver context.
lba
- Logical Block Address (sector number) to commence read.
len
- Number of bytes to read. This must be a multiple of the sector size.
buffer - Memory to receive data from on-disk sectors.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
153
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
2.26.4.5 USBH_BOMS_write
int8_t USBH_BOMS_write ( USBH_BOMS_context * ctx,
uint32_t
lba,
uint32_t
len,
uint8_t *
buffer
)
Write sectors to the BOMS device.
Write one or more sectors to the device. This blocks until the required amount of data is written.
Parameters
ctx
- Driver context.
lba
- Logical Block Address (sector number) to commence write.
len
- Number of bytes to write. This must be a multiple of the sector size.
buffer - Memory to source data from.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
2.26.4.6 USBH_BOMS_m ult_read_start
int8_t USBH_BOMS_mult_read_start ( USBH_BOMS_context * ctx,
uint32_t
lba,
uint32_t
len
)
Commence multiple sector reads from the BOMS device.
Start a read of multiple sectors from the device. The function does not block allowing data to be
processed as it is read. This allows large amounts of data to be streamed from the device without
using large amounts of memory to hold the data for processing.
The USBH_BOMS_mult_read_data() function is used to perform the read – which must take
exactly the number of bytes requested – before the USBH_BOMS_mult_end() function
completes the read. There must be no other BOMS operations while a multiple sector read
operation is in process.
Parameters
ctx - Driver context.
Lba - Logical Block Address (sector number) to commence read.
Len - Number of bytes to read. This must be a multiple of the sector size.
154
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
2.26.4.7 USBH_BOMS_m ult_write_start
int8_t USBH_BOMS_mult_write_start ( USBH_BOMS_context * ctx,
uint32_t
lba,
uint32_t
len
)
Commence multiple sector writes to the BOMS device.
Start a write of multiple sectors to the device. The function does not block allowing data t o be
generated as it is written. This allows large amounts of data to be streamed to the device without
using large amounts of memory to hold the data after generating it.
The USBH_BOMS_mult_write_data() function is used to perform the write – which must
receive exactly the number of bytes requested – before the USBH_BOMS_mult_end() function
completes the write. There must be no other BOMS operations while a multiple sector write
operation is in process.
Parameters
ctx - Driver context.
Lba - Logical Block Address (sector number) to commence write.
Len - Number of bytes to write. This must be a multiple of the sector size.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
2.26.4.8 USBH_BOMS_m ult_read_data
int8_t USBH_BOMS_mult_read_data ( USBH_BOMS_context * ctx,
uint32_t
len,
uint8_t *
buffer
)
Read sectors from the BOMS device during a multiple sector read.
Reads one or more sectors from a device after a multiple sector read ha s been started with
the USBH_BOMS_mult_read_start() function.
Parameters
ctx
- Driver context.
Len
- Number of bytes to read. This must be a multiple of the sector size.
Buffer - Memory to receive data.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
155
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.26.4.9 USBH_BOMS_m ult_write_data
int8_t USBH_BOMS_mult_write_data ( USBH_BOMS_context * ctx,
uint32_t
len,
uint8_t *
buffer
)
Write sectors to the BOMS device during a multiple sector write.
Writes one or more sectors to a device after a multiple sector write has been started with
the USBH_BOMS_mult_write_start() function.
Parameters
ctx
- Driver context.
Len
- Number of bytes to write. This must be a multiple of the sector size.
Buffer - Memory to source data from.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_PARAMETER length is not a multiple of the sector size.
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
2.26.4.10
USBH_BOMS_m ult_end
int8_t USBH_BOMS_mult_end ( USBH_BOMS_context * ctx )
Complete a multiple sector write or read.
Finishes a multiple sector write or read and checks the status.
Parameters
ctx - Driver context.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
2.26.4.11
USBH_BOMS_status
int8_t USBH_BOMS_status ( USBH_BOMS_context * ctx )
Get the device SCSI status.
Performs a SCSI Sense operation to retrieve the status of the BOMS device.
Parameters
ctx - Driver context.
Returns
USBH_BOMS_OK if successful
USBH_BOMS_ERR_SCSI if a SCSI (protocol error) occurred.
USBH_BOMS_ERR_STATUS the device returned a status error.
156
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.27 CDC ACM Devices on USB Host Stack API
The file ft900_usbh_cdcacm.h contains the definitions for the USB host CDC ACM functions in
the libft900.a library.
API functions for USB Host stack. These functions provide additional functionality useful to
implement a USB Host application.
Please refer to the documentation produced by the USB-IF covering CDC devices
including the Class Definitions for Communications Devices 1.2.API Cross Reference.
It utilises the following library APIs:
ft900_usbh.h – USB host
ft900_usbhx.h – USB host extensions
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_usb_cdc.h –USB CDC definitions
2.27.1 Macro Definition Documentation
2.27.1.1 Feature Configuration
#define CDCACM_FLAG_NO_NOTIFICATION
1
Do not expect or poll the notification endpoint in the Communication Class Interface.
#define CDCACM_IN_BUFFER
512
Size of internal receive circular buffe r for CDC DATA interface.
#define CDCACM_IN_MAX_PACKET
512
Maximum packet size of data which may be received. On High Speed devices this can be 512
bytes, on Full Speed this will be 64 bytes. The larger size will support both Full and High Speed
devices.
#define CDCACM_NOTIFICATION_BUFFER
12
Size of internal buffer used to hold notifications from the CDC CONTROL interface.
157
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.27.1.2 Library Return Codes
#define USBH_CDCACM_OK
0
Success for CDC function.
#define USBH_CDCACM_ERR_PARAMETER
-1
Parameter error in call to CDC function.
#define USBH_CDCACM_ERR_CLASS_NOT_SUPPORTED
-2
Device class not supported.
#define USBH_CDCACM_ERR_CLASS
-3
Class request not supported.
#define USBH_CDCACM_ERR_DATA_ENDPOINT
-5
Data Endpoints not found or polling failed.
#define USBH_CDCACM_ERR_FUNCTIONAL_DESCRIPTOR
-6
Function descriptor not found.
#define USBH_CDCACM_ERR_USB
-7
Unexpected USB error occurred.
158
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.27.2 Structure Documentation
2.27.2.1 USBH_CDCACM_context
CDC ACM device context.
Holds a context structure required by each instance of the driver.
Data Fields
USBH_device_handle
hControlDevice
USBH_interface_handle
hControlInterface
USBH_interface_handle
hDataInterface
USBH_endpoint_handle
hControlEpIn
USBH_endpoint_handle
hDataEpIn
USBH_endpoint_handle
hDataEpOut
uint8_t
controlInterfaceNumber
uint8_t
dataInterfaceNumber
uint8_t
callCapabilities
uint8_t
acmCapabilities
USB_CDC_UartStateBitmap
uartState
USB_CDC_UartStateBitmap
networkState
int8_t
responseAvailable
int8_t
notificationStatus
uint32_t
notificationBuffer [
CDCACM_NOTIFICATION_BUFFER/
sizeof(uint32_t)]
int8_t
recvStatus
uint32_t
recvPacket [
CDCACM_IN_MAX_PACKET/
sizeof(uint32_t)]
uint8_t
recvBuffer [CDCACM_IN_BUFFER]
volatile uint16_t
recvBufferWrite
volatile uint16_t
recvBufferRead
volatile uint16_t
recvBufferAvail
Field Documentation
hControlDevice
USB host device handle to the CDC device. There may be multiple CDC interfaces on the same
devices.
hControlInterface
USB host interface handle for CDC CONTROL interface .
159
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
hDataInterface
USB host interface handle for CDC DATA interface .
hControlEpIn
USB host endpoint handle for CDC CONTROL endpoint.
hDataEpIn
USB host endpoint handle for CDC DATA interface IN endpoint.
hDataEpOut
USB host endpoint handle for CDC DATA interface OUT endpoint.
controlInterfaceNumber
Interface number for CDC CONTROL interface. These are used in SETUP requests to identify the
correct interface.
dataInterfaceNumber
Interface number for CDC DATA interface. These are used in SETUP requests to identify the
correct interface.
callCapabilities
Call Management capabilities. Bitmap from Call Management Functional descriptor indicating the
method for managing calls on the device .
acmCapabilities
Abstract Control Management capabilities. Bitmap fro m Abstract Control Management Functional
descriptor indicating support for Comm, Line Coding, Break and Network features.
uartState
Notification bitmap for the UART state received from device .
networkState
Notification bitmap for the network state received from device.
responseAvailable
Response available notification flag indicating that an encapsulated response can be read from
the interface.
notificationStatus
Last status of CDC CONTROL notification poll from USB Host driver.
notificationBuffer
Buffer to receive notification structure from USB Host driver. This must be of type uint32_t to
follow alignment requirements of data buffers in USB Host driver.
recvStatus
Last status of CDC DATA IN endpoint poll from USB Host driver.
recvPacket
Buffer to receive data from the USB Host driver. This is exactly one MaxPacket size buffer. It
must be of type uint32_t to follow alignment requirements of data buffers in USB Host driver.
Note: can be of type uint8_t if it is qualified with: __attribute__ ((align ed (4))).
160
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
recvBuffer
Circular buffer used to group packet data from the USB Host. This does not have any alignment
issues.
recvBufferWrite
Write pointer for circular buffer (internal use).
recvBufferRead
Read pointer for circular buffer (internal use).
recvBufferAvail
Available space counters for circular buffer (internal use).
2.27.3 Function Documentation
2.27.3.1 USBH_CDCACM_init
int8_t USBH_CDCACM_init ( USBH_interface_handle
uint8_t
hControlInterface,
flags,
USBH_CDCACM_context * ctx
)
Initialise the CDC ACM driver.
Setup a context for the CDC driver to use the interfaces and settings provided in the call.
Parameters
hControlInterface - handle to the CDC CONTROL interface.
Flags
- CDCACM_FLAG_NO_NOTIFICATION to not poll notification e ndpoint.
Ctx
- Structure instantiated in the application to hold the context
information for this instance of the driver.
Returns
USBH_CDCACM_OK if successful
2.27.3.2 USBH_CDCACM_read
int32_t USBH_CDCACM_read ( USBH_CDCACM_context *
ctx,
uint8_t *
buffer,
size_t
len
)
Read data from the CDC ACM device.
Read a block of data from the CDC device DATA interface. The data is buffered internally in the
driver as it is produced by the CDC device and polled by the USB host. The buffer is designed to
discard incoming data if the internal buffer fills. Care must therefore be taken to ensure an
adequate consumption rate of data from the CDC device.
Parameters
ctx
- Context information for this instance of the driver.
161
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Buffer - receiving buffer.
Len
- Maximum length of data to read.
Returns
Number of bytes transferred to the receiving buffer. This may be less than the amount requested if
insufficient data has been received from the CDC device.
A negative value will represent an error on the USB host.
2.27.3.3 USBH_CDCACM_write
int32_t USBH_CDCACM_write ( USBH_CDCACM_context *
ctx,
uint8_t *
buffer,
size_t
len
)
Write data to the CDC ACM device.
Write a block of data to the CDC device DATA interface. Data is written immediately to the device
without buffering.
Parameters
ctx
- Context information for this instance of the driver.
Buffer - Transmission buffer.
Len
- Maximum length of data to write.
Returns
Number of bytes transferred from the transmissio n buffer to the device.
A negative value will represent an error on the USB host.
162
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.27.3.4 USBH_CDCACM_get_poll_status
void USBH_CDCACM_get_poll_status ( USBH_CDCACM_context * ctx,
int8_t *
notification_status,
int8_t *
data_status
)
Returns the last USB Host statuses for endpoint polling.
Each time an endpoint is polled the status is stored. Both the notification endpoint and the data IN
endpoint values are stored and can be queried by this functio n.
Parameters
ctx
- Context information for this instance of the driver.
Notification_status - Pointer to receive status of notification endpoint polling.
Data_status
- Pointer to receive status of data endpoint polling.
Returns
N/A.
2.27.3.5 USBH_CDCACM_set_com m _feature
int8_t USBH_CDCACM_set_comm_feature ( USBH_CDCACM_context *
ctx,
uint16_t
selector,
uint16_t
feature
)
Set Comm Features on the device.
The selector parameter is used to select between the abstract state and country setting data.
Parameters
ctx
- Context information for this instance of the driver.
Selector - Abstract State or Country Setting:
CDC_ACM_FEATURE_SELECTOR_ABSTRACT_STATE,
CDC_ACM_FEATURE_SELECTOR_COUNTRY_SETTING.
Feature - Bitmap to set the abstract state bitmap or country setting cod e.
Returns
USBH_CDCACM_OK – if the interface supports the COMM Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.6 USBH_CDCACM_clear_com m _feature
int8_t USBH_CDCACM_clear_comm_feature ( USBH_CDCACM_context * ctx,
uint16_t
selector
)
Clear the Comm Features on the device.
The selector parameter is used to select between the abstract state and country setting data.
163
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
ctx
- Context information for this instance of the driver.
Selector - Abstract State or Country Setting:
CDC_ACM_FEATURE_SELECTOR_ABSTRACT_STATE,
CDC_ACM_FEATURE_SELECTOR_COUNTRY_SETTING.
Returns
USBH_CDCACM_OK – if the interface supports the COMM Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.7 USBH_CDCACM_get_acm _capabilities
int8_t USBH_CDCACM_get_acm_capabilities ( USBH_CDCACM_context *
ctx )
Returns the ACM Capabilities bitmap.
Returns the bmCapabilities value obtained from the Abstract Control Management Functional
Descriptor for the CDC ACM interface.
Parameters
ctx - Context information for this instance of the driver.
Returns
Values are defined as CDC_ACM_CAPABILITIES_*
2.27.3.8 USBH_CDCACM_get_call_capabilities
int8_t USBH_CDCACM_get_call_capabilities ( USBH_CDCACM_context *
ctx )
Returns the Call Capabilities bitmap.
Returns the bmCapabilities value obtained from the Call Management Functional Descriptor for the
CDC ACM interface.
Parameters
ctx - Context information for this instance of the driver.
Returns
Values are defined as CDC_CM_CAPABILITIES_*
2.27.3.9 USBH_CDCACM_get_com m _feature
int8_t USBH_CDCACM_get_comm_feature ( USBH_CDCACM_context *
ctx,
uint16_t
selector,
uint16_t *
feature
)
Get a bitmap containing the currently set Comm Features.
The selector parameter is used to select between the abs tract state and country setting data.
Parameters
ctx
- Context information for this instance of the driver.
Selector - Abstract State or Country Setting:
CDC_ACM_FEATURE_SELECTOR_ABSTRACT_STATE,
CDC_ACM_FEATURE_SELECTOR_COUNTRY_SETTING.
164
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Feature - Bitmap to receive abstract state bitmap or country setting code.
Returns
USBH_CDCACM_OK – if the interface supports the COMM Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.10
USBH_CDCACM_get_encapsulated_response
int8_t USBH_CDCACM_get_encapsulated_response ( USBH_CDCACM_context *
ctx,
char *
rsp,
uint16_t
len
)
Read an encapsulated command response from the CDC ACM device.
Read a block of data from the CDC device control interface. Data is read immediately to the device
without buffering.
Parameters
ctx - Context information for this instance of the driver.
Rsp - receive buffer for receiving response.
Len - Maximum length of data to receive.
Returns
Number of bytes transferred from the device to the receive buffer.
2.27.3.11
USBH_CDCACM_get_line_coding
int8_t USBH_CDCACM_get_line_coding ( USBH_CDCACM_context *
USB_CDC_line_coding *
ctx,
coding
)
Get Current Line Coding settings from the device.
The USB_CDC_line_coding structure describes the data output format on the ‘UART’ side of the
CDC device. This will query the settings and return them in the structure.
Parameters
ctx
- Context information for this instance of the driver.
Coding - Pointer to structure containing the currently set parameters for formatting data.
Returns
USBH_CDCACM_OK – if the interface supports the Line Coding Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.12
USBH_CDCACM_set_line_coding
int8_t USBH_CDCACM_set_line_coding ( USBH_CDCACM_context *
USB_CDC_line_coding *
ctx,
coding
)
Set Line Coding on the device.
165
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
The USB_CDC_line_coding structure is used to set the data output format on the CDC device.
This is on the ‘UART’ side of the device.
Parameters
ctx
- Context information for this instance of the driver.
Coding - Pointer to structure containing the requested parameters for formatting data.
Returns
USBH_CDCACM_OK – if the interface supports the Line Coding Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.13
USBH_CDCACM_get_network_connection
uint8_t
USBH_CDCACM_get_network_c
onnection
( USBH_CDCACM_context *
ctx,
USB_CDC_NetworkConnectionBitmap * state
)
Returns the Network state bitmap.
When a notification arrives updating the Network state this is kept in the driver and can be queried
by this command.
Parameters
ctx
- Context information for this instance of the driver.
State - Pointer to structure to receive last received state.
Returns
USBH_CDCACM_OK – if the interface supports the Network_Connection notification.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.14
USBH_CDCACM_get_uart_state
uint8_t USBH_CDCACM_get_uart_state ( USBH_CDCACM_context *
ctx,
USB_CDC_UartStateBitmap * state
)
Returns the UART state bitmap.
When a notification arrives updating the UART state this is kept in the driver and can be queried by
this command.
Parameters
ctx
- Context information for this instance of the driver.
State - Pointer to structure to receive last received state.
Returns
USBH_CDCACM_OK – if the interface supports the Serial_State notification.
USBH_CDCACM_ERR_CLASS – if it does not support it.
166
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.27.3.15
C learance N o.: FT DI#453
USBH_CDCACM_set_control_line_state
int8_t USBH_CDCACM_set_control_line_state ( USBH_CDCACM_context *
ctx,
USB_CDC_control_line_state * state
)
Set Control Line State on the device.
The USB_CDC_control_line_state structure is used to set the state of the control lines on the
CDC device. This is on the ‘UART’ side of the device.
Parameters
ctx
- Context information for this instance of the driver.
State - Pointer to structure containing the requested state for the control lines.
Returns
USBH_CDCACM_OK – if the interface supports the Line Coding Feature requests.
USBH_CDCACM_ERR_CLASS – if it does not support it.
2.27.3.16
USBH_CDCACM_get_response_available
int8_t USBH_CDCACM_get_response_available ( USBH_CDCACM_context * ctx )
Indicates the response to an encapsulated command is waiting.
When a notification arrives indicating that a response to a encapsulated command is waiting to be
read this is kept in the driver and can be queried by this command.
Parameters
ctx - Context information for this instance of the driver.
Returns
Non-zero if a encapsulated response is available.
2.27.3.17
USBH_CDCACM_send_encapsulated_com m and
int8_t USBH_CDCACM_send_encapsulated_command ( USBH_CDCACM_context *
ctx,
char *
cmd,
uint16_t
len
)
Send an encapsulated command to the CDC ACM device.
Write a block of data to the CDC device control interface. Data is written immediately to the device
without buffering.
Parameters
ctx
- Context information for this instance of the driver.
Cmd - Transmission buffer containing command.
Len - Maximum length of data to write.
Returns
Number of bytes transferred from the transmission buffer to the device.
167
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.27.3.18
C learance N o.: FT DI#453
USBH_CDCACM_send_break
int8_t USBH_CDCACM_send_break ( USBH_CDCACM_context *
uint16_t
ctx,
duration
)
Instructs the device to set a break state on the UART line.
Parameters
ctx
- Context information for this instance of the driver.
Duration - Length of time in milliseconds to set the break state.
Returns
USBH_CDCACM_OK – if the interface supports the Send_Break request.
USBH_CDCACM_ERR_CLASS – if it does not support it.
168
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.28 Android Open Accessory (AOA) Devices on USB Host
Stack API
The file ft900_usbh_aoa.h contains the definitions for the USB host AOA functions in the
libft900.a library.
Please refer to the Android AOA Documentation at:
https://source.android.com/devices/accessories/aoa2.html for more details on AOA features and
protocol.
2.28.1 API Cross Reference
It utilizes the following libraries:
ft900_usbh.h – USB host
ft900_usbhx.h – USB host extensions
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_usb_aoa.h – AOA definitions
2.28.2 Macro Definition Documentation
2.28.2.1 Library Return Codes
#define USBH_AOA_OK 0
Success for AOA function.
#define USBH_AOA_DETECTED 1
AOA device detected in accessory mode. Device is ready to use.
#define USBH_AOA_STARTED 2
AOA device detected in accessory mode. Device has been restarted and need reenumerated.
#define USBH_AOA_ERR_PARAMETER -1
Parameter error in call to AOA function.
#define USBH_AOA_ERR_CLASS_NOT_SUPPORTED -2
Device class not supported.
#define USBH_AOA_ERR_CLASS -3
Class request not supported.
#define USBH_AOA_ERR_PROTOCOL -4
AOA Protocol not supported.
#define USBH_AOA_ERR_CONFIG -5
AOA Protocol configuration error.
#define USBH_AOA_ERR_ENDPOINT -6
Data Endpoints not found or polling failed.
#define USBH_AOA_ERR_USB -7
Unexpected USB error occurred.
169
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.28.3 Structure Documentation
2.28.3.1 USBH_AOA_context
AOA device context.
Holds a context structure required by each instance of the driver.
Data Fields
USBH_device_handle
hDevAccessory
uint16_t
vid
uint16_t
pid
USBH_interface_handle hAccessoryInterface
USBH_endpoint_handle
hAccessoryEpIn
USBH_endpoint_handle
hAccessoryEpOut
USBH_interface_handle hAdbInterface
USBH_endpoint_handle
hAdbEpIn
USBH_endpoint_handle
hAdbEpOut
USBH_interface_handle hAudioInterface
USBH_endpoint_handle
hAudioEp
uint16_t
maxIsoSize
uint16_t
protocol
uint16_t
HIDDescriptorSize
Field Documentation
hDevAccessory
Handle to the AOA device.
Vid, pid
VID and PID of device when in accessory mode
hAccessoryInterface
Interface handle for AOA general interface.
hAccessoryEpIn
Endpoint handles for the AOA general interface.
hAdbInterface
Interface handle for AOA adb interface
hAdbEpIn, hAdbEpOut
Endpoint handles for the AOA adb interface .
hAudioInterface
Interface handle for AOA audio interface .
hAudioEp
Audio device endpoint handle.
170
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
maxIsoSize
Maximum packet size of audio isochronous endpoint.
Protocol
Android Open Accessory Protocol version.
HIDDescriptorSize
Size of HID descriptor.
2.28.4 Function Documentation
2.28.4.1 USBH_AOA_init
int8_t USBH_AOA_init ( USBH_interface_handle
USBH_AOA_context
hAOAInterface,
*ctx,
USBH_AOA_descriptors * descriptors,
int16_t
audio
)
Initialise the AOA driver.
The sequence for connecting to AOA devices is:
1) Check AOA protocol is valid. This means that the special vendor SETUP command works and the
return value is non-zero and matches a protocol version supported by the driver.
2) Send string descriptors to the AOA device using the vendor SETUP commands. Then send a
start accessory device vendor SETUP command.
3) The device re-enumerates by doing a device reset.
4) The host re-enumerates the device as an Android accessory.
The device will need to be attached using USBH_AOA_attach() once it has been re-enumerated.
Parameters
hAOAInterface - handle to the AOA interface to use.
Descriptors
- Pointer to a structure containing string descriptors to send to the AOA
device.
Ctx
- Structure instantiated in the application to hold the context information
for this instance of the driver.
Audio
- if the protocol supports audio then send the enable audio command to
the accessory to enable the audio interface
Returns
USBH_AOA_STARTED if an Android accessory device in its normal mode was detected. It will have
been started as an accessory and will therefore perform a device reset and be re -enumerated.
USBH_AOA_DETECTED if an Android accessory device in accessory mode was detected. This
device can now be attached and used. USBH_AOA_ERR_CLASS_NOT_SUPPORTED if a device
which is not an Android accessory was detected.
171
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.28.4.2 USBH_AOA_attach
int8_t USBH_AOA_attach ( USBH_AOA_context *ctx)
Attaches to the AOA device.
Connects to the AOA device which is in accessory mode. It will decode the AOA protocol, VID and
the PID to determine support for accessories, adb bridge and audio. Endpoints and size
information is stored for use by the driver later.
Parameters
ctx - context of AOA device to use.
Returns
USBH_AOA_OK if successful
USBH_AOA_ERR_CONFIG if a device re porting to possess a particular interface does not, in fact,
present that interface. USBH_AOA_ERR_CLASS_NOT_SUPPORTED if a device which is not an
Android accessory was detected.
2.28.4.3 USBH_AOA_detach
int8_t USBH_AOA_detach ( USBH_AOA_context *ctx)
Detaches from the AOA device.
Parameters
ctx - context of AOA device to use.
Returns
USBH_AOA_OK if successful
2.28.4.4 USBH_AOA_get_protocol
int8_t USBH_AOA_detach ( USBH_AOA_context *ctx)
Detaches from the AOA device.
Parameters
ctx
- Context of AOA device to use.
Protocol - pointer to BCD protocol revision
Returns
This will return a positive value if the device supports the accessory class. Zero if it does not.
Negative if there was an error.
2.28.4.5 USBH_AOA_has_accessory
int8_t USBH_AOA_has_accessory ( USBH_AOA_context *ctx)
AOA device supports accessories.
Parameters
ctx - Context of AOA device to use.
Returns
This will return a positive value if the device supports the accessory class. Zero if it does not.
Negative if there was an error.
172
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.28.4.6 USBH_AOA_has_audio
int8_t USBH_AOA_has_audio ( USBH_AOA_context *ctx)
AOA device supports audio.
Parameters
ctx - Context of AOA device to use.
Returns
This will return a positive value if the device supports the audio class. Zero if it does not. Negative
if there was an error.
2.28.4.7 USBH_AOA_has_adb
int8_t USBH_AOA_has_adb ( USBH_AOA_context *ctx)
AOA device supports adb.
Parameters
ctx - Context of AOA device to use.
Returns
This will return a positive value if the device supports the adb class. Zero if it does not. Negative if
there was an error.
2.28.4.8 USBH_AOA_get_audio_endpoint
int8_t USBH_AOA_get_audio_endpoint ( USBH_AOA_context
*ctx,
USBH_endpoint_handle * hAudio,
uint16_t *
maxSize
)
Gets a handle to the audio endpoint. If the AOA device supports it then the audio isochronous
endpoint can be obtained with this call.
Parameters
ctx
- Context of AOA device to use.
hAudio
- Pointer to handle to receive audio endpoint.
maxSize - Max size of the audio endpoint
Returns
USBH_AOA_OK if successful.
2.28.4.9 USBH_AOA_register_hid
int8_t USBH_AOA_register_hid ( USBH_AOA_context *ctx,
uint16_t
hidID,
uint16_t
descriptorSize
)
Register a new HID device.
173
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Parameters
ctx
- Context of AOA device to use.
hidID
- ID of new HID device
descriptorSize - Number of bytes in HIDs report descriptor. This is sent separately as it
can be changed.
Returns
USBH_AOA_OK if successful.
2.28.4.10
USBH_AOA_unregister_hid
int8_t USBH_AOA_register_hid ( USBH_AOA_context *ctx,
uint16_t
hidID
)
Unregister a HID device.
Parameters
ctx
- Context of AOA device to use.
hidID - ID of previously registered HID device
Returns
USBH_AOA_OK if successful.
2.28.4.11
USBH_AOA_set_hid_report_descriptor
int8_t USBH_AOA_set_hid_report_descriptor ( USBH_AOA_context *ctx,
uint16_t
hidID,
uint16_t
descriptorOffset,
uint16_t
descriptorLength,
uint8_t *
descriptor
)
Set the HID descriptor for a HID device.
Parameters
ctx
- Context of AOA device to use.
hidID
- ID of previously registered HID device
descriptorOffset
- used when the HID descriptor is sent in multiple packets. This is the
offset to the position in the descriptor where this fragment goes.
descriptorLength - Length of this section of HID descriptor. If the HID descriptor is sent
in one packet then this will be the same as the length set in
descriptorSize parameter of USBH_AOA_register_hid. If the descriptor
is made up of multiple packets then the length will be smaller.
Descriptor
- HID descriptor.
174
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
2.28.4.12
C learance N o.: FT DI#453
USBH_AOA_send_hid_data
int8_t USBH_AOA_send_hid_data ( USBH_AOA_context *ctx,
uint16_t
hidID,
uint16_t
reportSize,
uint8_t *
data,
)
Send a report descriptor to the AOA device.
Parameters
ctx
- Context of AOA device to use.
hidID
- ID of previously registered HID device
reportSize - Number of bytes in HIDs report.
Data
- Report data.
2.29 Startup DFU Feature
The file ft900_startup_dfu.h contains the definitions for the USB start up DFU device functions in
the libft900.a library.
The Startup DFU library allows an application to enable the USB device on the FT900 temporarily
to present a DFU interface to the USB host. Software on the USB host can then update the
application stored in Flash on the FT900 regardless of the functionality or features of the existing
application.
The feature can be added to any application by adding a call to the function STARTUP_DFU. This
call can be made under any conditions – maybe a button press at power-up detected by a GPIO or
just unconditionally when the application is started.
The USB interface remains active for a short period of time (~200ms) and once activated by
enumeration from the USB host will continue to stay active for around 1000ms after activity has
ceased.
This file contains Startup DFU feature function definitions, constants and structures which are
exposed in the API.
Note that as this is a USB device all transaction nomenclature is from the point of view from the
host. If the device sends data to the host then it is called an IN transaction, if it receives data from
the host then it is an OUT transaction.
2.29.1 API Cross Reference
It utilises the following library APIs:
ft900_timers.h – Timers
ft900_sys.h – Chip Management
ft900_interrupt.h – Interrupt Management
ft900_usbd.h – USB device
Additional definitions are taken from:
ft900_usb.h – General USB definitions
ft900_usb_dfu.h –USB DFU definitions
175
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.29.2 Function Documentation
2.29.2.1 STARTUP_DFU
void STARTUP_DFU ( void
)
Temporarily start the USB device with a DFU interface.
When called, the USB device will be enabled for around 200ms allowing a USB host to enumerate
the device. Once enumerated, the function will wait for around 1000ms for a DFU connection from
the USB host. This will allow a program on the host PC to download new firmware to the device.
The function returns after one of the timeouts has completed. If the firmware on the device is
updated or the device is reset via a USB reset then the device will be reset.
176
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.30 SD Host
The file ft900_sdhost.h contains the definitions for the SD card device functions in the libft900.a
library.
2.30.1 Enumeration Type Documentation
2.30.1.1 sdhost_cm d_t
enum sdhost_cmd_t
Enumerator
SDHOST_BUS_CMD
SDHOST_APP_SPECIFIC_CMD
2.30.1.2 sdhost_response_t
enum sdhost_response_t
Enumerator
SDHOST_RESPONSE_NONE
SDHOST_RESPONSE_R1
SDHOST_RESPONSE_R1b
SDHOST_RESPONSE_R2
SDHOST_RESPONSE_R3
SDHOST_RESPONSE_R4
SDHOST_RESPONSE_R5
SDHOST_RESPONSE_R5b
SDHOST_RESPONSE_R6
SDHOST_RESPONSE_R7
2.30.1.3 SDHOST_STATUS
enum SDHOST_STATUS
Enumerator
SDHOST_OK
SDHOST_ERROR
SDHOST_CARD_INSERTED
177
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
SDHOST_CARD_REMOVED
SDHOST_INVALID_RESPONSE_TYPE
SDHOST_CMD_TIMEOUT
SDHOST_UNUSABLE_CARD
SDHOST_CMD2_FAILED
SDHOST_CMD3_FAILED
SDHOST_CMD8_FAILED
SDHOST_CMD9_FAILED
SDHOST_CMD55_FAILED
SDHOST_ACMD41_FAILED
SDHOST_CANNOT_ENTER_TRANSFER_STATE
SDHOST_CANNOT_SET_CARD_BUS_WIDTH
SDHOST_RESPONSE_ERROR
SDHOST_WRITE_ERROR
SDHOST_READ_ERROR
2.30.2 Function Documentation
2.30.2.1 sdhost_abort
SDHOST_STATUS sdhost_abort ( void
)
Abort current sdhost operation.
Returns
SDHOST_OK if successful
2.30.2.2 sdhost_card_detect
SDHOST_STATUS sdhost_card_detect ( void
)
Check to see if a card is inserted.
Returns
SDHOST_CARD_INSERTED if a card is inserted.
SDHOST_CARD_REMOVED if no card is inserted.
2.30.2.3 sdhost_card_init
SDHOST_STATUS sdhost_card_init ( void
)
Identifies and initializes the inserted card.
Returns
178
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
either SDHOST_ERROR or SDHOST_OK
2.30.2.4 sdhost_init
void sdhost_init ( void
)
Function initializes SD Host device.
2.30.2.5 sdhost_sys_init
void sdhost_sys_init ( void
)
Function used for initializing system registers.
2.30.2.6 sdhost_transfer_data
SDHOST_STATUS sdhost_transfer_data ( uint8_t
void *
direction,
buf,
uint32_t numBytes,
uint32_t addr
)
Transfer data to/from SD card.
Parameters
direction SDHOST_READ or SDHOST_WRITE
buf
address of memory data to be read or write
numBytes size of data to be read or written
addr
address of SD card to write to or read from
Returns
SDHOST_STATUS enum indicating on outcome of operation.
2.31 Datalogger Feature
FT900 provides several peripherals which may be interfaced to output or storage devices.
Developers may use any of these peripherals to output debug or diagnostic information during
development. Peripherals attached to storage (SPI flash, SD Card memory, USB Mass Storage,
etc.) may be used to store such information, too. However, there are customer applications in
which no external storage is available and it becomes impossible to capture and store debug or
diagnostic information collected in the field. The datalogger feature uses the on-chip flash in the
FT900 for such storage.
FT900 has 256KB of flash. The flash is organized as a multiple of blocks. Blocks are made up of
sectors and sectors in turn are made up of pages. The smallest programmable unit is a page and
the smallest erasable unit is a sector. The following table describes the flash geometry in FT900.
Memory Organization
Multiples
Units
Size
Complete Flash
4
Blocks
256 KB
179
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Block
16
Sectors
64 KB
Sector
16
Page
4 KB
Page
256
Bytes
256 B
Table 1 – FT900 Flash Geometry
2.31.1 Datalogger Partition
The datalogger partition occupies one sector of the flash and is 4KB in size. As mentioned in Table
1 – FT900 Flash Geometry, there are 16 pages in one sector. The first and last pages are reserved
and the remaining 14 pages are available to the user application for usage. User application refers
to the 14 pages via page index 0 to 13.
Once a page has been programmed, it may not be programmed again. In order to overwrite a
previously programmed page, the partition has to be erased.
Res erved Page
256 bytes
14 user
programmable
pages
Res erved Page
Datalogger Partition (4KB)
Figure 2-1 Datalogger Partition
2.31.2 API Cross Reference
It utilizes the following libraries:
ft900_memctl.h– FT900 memory controller driver
The file ft900_dlog.h contains the definitions for the datalogger feature functions in the libft900.a
library.
2.31.3 Variable Documentation
2.31.3.1 __dlog_partition
extern __flash__ uint32_t __dlog_partition[] ;
The global variable__dlog_partition has to be referenced in the user application through an extern.
The __dlog_partition variable is defined in the C runtime for a datalogger application. This value is
passed to the dlog_init() API function. The __flash__ attribute informs the compiler that this is a
pointer to flash memory.
180
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.31.4 Function Documentation
2.31.4.1 dlog_init
/**<
* @function dlog_init
* @brief
read one page of data
* @param
[in]
flashbuf
pointer to flash datalog partition
* @param
[out] pgsz
size of page on flash
* @param
[out] pages
number of pages in partition, pg=1..pages
* @returns 0
on success
*
-1
if partition is invalid
*/
int dlog_init (__flash__ uint32_t *flashbuf, int *pgsz, int *pages);
dlog_init must be the first function to be called to initialize the datalogger API. Set flashbuf to
__dlog_partition. On successful return, pgsz and pages shall be initialized. Pgsz indicates the
size of the page in flash and pages indicates the number of pages available in the partition. In the
present API, pgsz is fixed to 256 bytes and pages is fixed to 14.
Dlog_init does not keep track of which pages were programmed and which pages remain erased.
Such page management is left to the user application.
2.31.4.2 dlog_erase
/**<
* @function dlog_erase
* @brief
erases the datalog partition and writes the partition signatures
* @param
none
* @returns 0
datalog partition was erased
*
-1
datalog library has not been initialized
*/
int dlog_erase (void);
dlog_erase is called without any parameters. This function is used to erase the flash partition.
Dlog_erase programs the first and last pages with the datalogger signature.
2.31.4.3 dlog_read
/**<
* @function
* @brief
* @param
* @param
* @returns
*
*/
dlog_read
read one page of data
[in]
pg
page number, valid range 0..13
[out] data
32-bit pointer to buffer of page size length
0
on success
-1
if pg or data are invalid
int dlog_read (int pg, uint32_t *data);
dlog_read is used to read pages from the datalogger partition. Pg is an input argument and
denotes the user page number to read. Valid values for pg are 0 to 13. Data is an output 32-bit
pointer into which page content is transferred to.
181
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.31.4.4 dlog_prog
/**<
* @function dlog_prog
* @brief
program one page of data
* @param
[in]
pg
page number, valid range 0..13
* @param
[in]
data
32-bit pointer to buffer of page size length
* @returns 0
on success
*
-1
if pg or data are invalid
*/
int dlog_prog (int pg, uint32_t *data);
dlog_prog is used to program pages with user data. Pg is an input argument and denotes the
user page number to program. Valid values for pg are 0 to 13. No check is made if a page was
previously programmed. Data is an input 32-bit pointer containing the information to be
programmed.
2.32 D2XX Feature
The D2XX interface is a proprietary interface specifically for FTDI devices. A D2XX channel
connects two processes; the D2XX application on the USB Host and the user application executing
on the FT900. Data is exchanged transparently between the peer applications at each end of the
channel. It shall relieve the user firmware from dealing with any USB related communication.
D2XX library API calls for the purpose are:
D2XX_Init() – To provide user configuration and initialize the D2XX Solution library.
D2XX_Exit() – To exit D2XX mode and USB device is released to the system.
D2XX_Read() – A read returns data from the D2XX channel. If the channel is empty, zero
bytes are returned
D2XX_Write() – A write loads data into the D2XX channel. If the channel is full, the data is
not accepted into the channel
D2XX_IOCTL() – Can be used to for interface related controls
Figure 2-2 D2XX Solution Context Diagram
2.32.1 API Cross Reference
It utilises the following library APIs:
ft900_sys.h – Chip Management
ft900_interrupt.h – Interrupt Management
182
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
ft900_usbd.h – USB device API
Additional definitions are taken from
ft900_usb.h – General USB definitions
ft900_usb_dfu.h – USB DFU class definitions
2.32.2 Variable Documentation
2.32.2.1 __dlog_partition
extern TD2XX_DeviceConfiguration __pD2XXDefaultConfiguration[] ;
The
global
variable
indicating
start
of
d 2xx
partition
in
flash.
__pD2XXDefaultConfiguration has to be referenced in the user application through an extern.
The __pD2XXDefaultConfiguration variable is defined in the C runtime for a d2xx firmware
application. This value is passed to the D2XX_Init() API function.
2.32.3 Macro Definition Documentation
#define D2XX_MAX_INTERFACES (3)
The maximum number of D2XX interfaces the D2XX solution for FT900 can support.
#define D2XX_MAX_DESCRIPTOR_STRING_SIZE (128)
The maximum total length of all the four strings used in the string descriptors. Refer
TD2XX_DeviceConfiguration for the details on the strings used.
#define D2XX_DEVICEGUID_STRING_SIZE (40)
Double Null terminated ASCII string for Unique device interface GUID in registry format (including
Braces and hyphen) for. E.g.: {2C69C451-55E9-46f0-8E4E-1F30D1E148EE}.
#define D2XX_API_ERR_BASE (-1)
A non-zero, negative, number base to start the error coding for the Enum ED2XX_ErrorCode.
2.32.4 Structure Documentation
2.32.4.1 TproductDescriptors
Struct to provide the product specific information about D2XX USB device.
Fields:
uint16_t VendorID
Vendor ID (assigned by the USB-IF)
uint16_t ProductID
Product ID (assigned by the manufacturer)
2.32.4.2 TconfigDescriptors
Struct to provide the configuration descriptor information about D2XX USB device.
Fields:
183
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
uint8_t BCDEnable
Battery Charge Detection to be enabled or not. 0=disable,
1=enable
uint8_t DFUCapable
DFU support. 0=disable, 1=enable
uint8_t SelfPowered
Bus or Self Powered Device. 0=disable, 1=enable
uint8_t MaxPower
Maximum power consumption of the USB device from the bus
in this specific configuration when the device is fully
operational. Expressed in 2 mA units (i.e., 50 = 100 mA).
Uint8_t NumOfD2XXInterfaces
Number of D2XX interfaces supported by this USB
configuration. Range: 1 to D2XX_MAX_INTERFACES
uint8_t RMWKUPEnable
Remote Wakeup capable or not. 0=disable, 1=enable
uint16_t MaxTransferSize
The maximum packet size for which transfer happens on
each of the D2XX interfaces. Value: 0 or enum values defined
in ED2XX_TransferSize. Fill the value to 0 if a d2xx interface
is not used (i.e. Indexes >= NumOfD2XXInterfaces)
2.32.4.3 TD2XX_Dev iceConfiguration
Fields:
TproductDescriptors ProductDesc
Struct to provide the product specific information about
D2XX USB device.
TconfigDescriptors ConfigDesc
Struct to provide the configuration descriptor information
about D2XX USB device.
Uint8_t Strings
String configuration section. String 1 – ASCII string detailing
the manufacturer.
String 2 – ASCII string detailing the Product.
String 3 – ASCII string for the Serial Number.
String 4 – ASCII string for the DFU Runtime Interface Name.
Note:
All the strings should be preceded with the data length of the
string. For e.g.
0x04,’F’,’T’,’D’,’I’,
0x0A,’F’,’T’,’9’,’0’,’0’,’ ‘,’D’,’2’,’X’,’X’,
0x0E,’F’,’T’,’9’,’0’,’0’,’S’,’e’,’r’,’’'’'’'’'’'’'’'’'’'’'’',
2.32.5 Enumeration Type Documentation
2.32.5.1 ED2XX_ErrorCode
The return values returned by the API functions.
D2XX_ERR_NONE = 0
returns Success
D2XX_ERR_IO = D2XX_API_ERR_BASE
in case of IO operation error
D2XX_ERR_MULTI = D2XX_API_ERR_BASE-1
in case of multiple call of the init or exit API
D2XX_ERR_DEVICE = D2XX_API_ERR_BASE-2
in case of Device error
D2XX_ERR_INSUFFICIENT_RESOURCES = D2XX_API_ERR_BASE-3
insufficient memory or resources
in case of
D2XX_ERR_INVALID_PARAMETER = D2XX_API_ERR_BASE-4
to API function
Invalid Parameter supplied
D2XX_ERR_NOT_SUPPORTED = D2XX_API_ERR_BASE-5
Operation not supported
184
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.32.5.2 ED2XX_Ev entCode
The events for which the D2XX API provides callback.
D2XX_EVT_SUSPEND
SUSPEND EVENT from USB Host
D2XX_EVT_RESUME
RESUME EVENT from USB Host
D2XX_EVT_RESET
RESET Vendor Command from D2XX Application
D2XX_EVT_READY
D2XX enters Ready state where READ/WRITE requests are
processed
D2XX_EVT_UNREADY
D2XX exits Ready state (USB disconnected)
D2XX_EVT_DFU_DETACH
DFU DETACH Class command from DFU application
D2XX_EVT_TESTMODE
D2XX enters Test Mode. Exit is via power cycle
D2XX_EVT_MAX_CODE
2.32.5.3 ED2XX_IoctlID
The ioctl id is the unique identifier used by the D2XX IOCTL API to process the ioctl request.
D2XX_IOCTL_SYS_REMOTE_WAKEUP
REMOTE WAKEUP to the USB Host
D2XX_IOCTL_INTERFACE_WAKEUP
D2XX interface wakeup to be sent for a D2XX
interface
D2XX_IOCTL_MAX_ID
End of IOCTL ID List
2.32.5.4 ED2XX_TransferSize
The maximum packet size for which transfer happens on the D2XX interface.
D2XX_XFER_SIZE_32 = 32
32 Bytes
D2XX_XFER_SIZE_64 = 64
64 Bytes
D2XX_XFER_SIZE_128 = 128
128 Bytes
D2XX_XFER_SIZE_256 = 256
256 Bytes
D2XX_XFER_SIZE_512 = 512
512 Bytes
D2XX_XFER_SIZE_1024 = 1024 1024 Bytes
2.32.6 Typedef Documentation
2.32.6.1 FD2XX_Callback
typedef void (*FD2XX_Callback)(ED2XX_EventCode eventID, void *ref, void* param1, void* param2);
Callback declaration for user callback functions invoked from D2XX solution.
Parameters
[in] eventID The events for which the D2XX provides callback
[in] ref
User application context which is stored and given back during invocation of
callback functions on events.
[in] param1 In case of D2XX_EVT_SUSPEND, this PARAM gives whether the
RemoteWakeup is enabled or not.
185
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
1 – Enabled
0 – Disabled
Based on which the user application can issue a Remote Wakeup to the host
device in Suspend mode.
[in] param2 Currently unused.
Returns
void
2.32.7 Function Documentation
2.32.7.1 D2XX_Init
ED2XX_ErrorCode D2XX_Init(TD2XX_DeviceConfiguration *d2xxDeviceConfig, FD2XX_Callback
callbackFn, void *ref)
Initialises D2XX solution library. This function MUST be called prior to any further call to the USB
functions.
Parameters
[in] d2xxDeviceConfig User application custom specific information about the D2XX USB
device and its interfaces. This data is used in the construction of
device, config and string descriptors.
[in] callbackFn
The user application registers its callback function through this
param.
[in] ref
The user application registers its callback context through this
param.
Returns
D2XX_ERR_NONE if successful.
D2XX_ERR_INVALID_PARAMETER if invalid values or ranges provided through the
d2xxDeviceConfig param.
2.32.7.2 D2XX_Exit
void D2XX_Exit(void)
Application to call this function to exit D2XX mode. This function cleans up D2XX solution and USB
Driver.
Returns
void
186
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.32.7.3 D2XX_Read
int32_t D2XX_Read(int32_t interfaceNum, uint8_t *readBuffer, const int32_t length)
Performs Read on a D2XX interface.
Parameters
[in] interfaceNum D2XX Interface Number Range: 1..n, n -> Number of D2XX Interfaces
configured by the application
[in] readBuffer
A pointer to the buffer which the stream data is read into.
[in] length
The number of bytes of data to read from D2XX interface buffer.
Returns
Returns the actual number of bytes read from the D2XX interface.
Zero bytes are returned if the internal D2XX buffer is empty.
D2XX_ERR_INVALID_PARAMETER if invalid values or ranges provided through the
interfaceNum or readBuffer params.
D2XX_ERR_IO if unsuccessful.
D2XX_ERR_DEVICE if D2XX is not in the state of processing the request
2.32.7.4 D2XX_Write
int32_t D2XX_Write(int32_t interfaceNum, uint8_t *writeBuffer, const int32_t length)
Performs Write on a D2XX interface.
Parameters
[in]
interfaceNum D2XX Interface Number Range: 1..n, n -> Number of D2XX
Interfaces configured by the application
[in,out] writeBuffer
[in]
length
A pointer to the buffer to which the stream data is written to.
The number of bytes of data to write from user buffer to the D2XX
interface.
Returns
Returns the actual number of bytes written to the D2XX interface.
Zero bytes are returned if the internal D2XX buffer is full.
D2XX_ERR_INVALID_PARAMETER if invalid values or ranges provided through the
interfaceNum or writeBuffer params.
D2XX_ERR_IO if unsuccessful.
D2XX_ERR_DEVICE if D2XX is not in the state of processing the request
187
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
2.32.7.5 D2XX_IOCTL
ED2XX_ErrorCode D2XX_IOCTL(int32_t interfaceNum, ED2XX_IoctlID ioctlID, void *param1,
void *param2)
The ioctl API is a catch-all that can handle transactions where read and write are not suitable.
Typically, this means control data for a D2XX interface or system control of USB device.
Parameters
[in] interfaceNum D2XX Interface Number Value: 0–- System Purpose (e.g. Remote
Wakeup) 1..n, n -> Number of D2XX Interfaces configured by the
application
[in] ioctlID
D2XX IOCTL ID Refer to ED2XX_IoctlID documentation
[in] param1
Additional Parameter that application passes for
D2XX_IOCTL_INTERFACE_WAKEUP. It is for set or clear 1 -> Set
Wakeup 0 -> Clear Wakeup
[in] param2
Currently unused.
Returns
D2XX_ERR_NONE if successful.
D2XX_ERR_INVALID_PARAMETER if invalid values or ranges provided through the
interfaceNum or ioctlID params.
D2XX_ERR_DEVICE if D2XX is not in the state of processing the request
D2XX_ERR_NOT_SUPPORTED if any unsupported IOCTL request is made.
188
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
3 Header Files
3.1 Hardware Register Definition Files
The following is a list of all hardware register definition files. These are loca ted in the
inc/registers directory.
ft900_adc_dac_registers.h
ADC/DAC registers
ft900_cam_registers.h
Camera/Parallel interface registers
ft900_can_registers.h
CANBus registers
ft900_ehci_registers.h
EHCI Registers
ft900_eth_registers.h
Ethernet registers
ft900_flash_registers.h
ft900_gpio_registers.h
General Purpose IO and Pad control registers
ft900_i2c_registers.h
I2C registers
ft900_i2s_registers.h
I2S registers
ft900_interrupt_registers.h
Interrupt management registers
ft900_pwm_registers.h
Pulse Width Modulation registers
ft900_registers.h
FT900 Registers
ft900_rtc_registers.h
Real Time Clock Registers
ft900_sdhost_registers.h
SD Host Registers
ft900_spi_registers.h
SPI Registers
ft900_sys_registers.h
Chip management registers
ft900_timer_wdt_registers.h
Timer and Watchdog Registers
ft900_uart_registers.h
UART Registers
ft900_usbd_registers.h
USBD Registers
3.1.1
Using Register Header Files
The register header files can be used to directly access the device registers.
Here are the steps involved:
1. Find the module define in ft900_registers.h
2. Find the register to access in the associated register header file.
3. Decide if any of the constants will be used to help set or clear specific bit fields
189
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
3.1.1.1 Exam ple 1 –Read a Register
To read the Chip ID Register in the General System Registers:
uint32_t HIPID_value;
HIPID_value = SYS->HIPID;
3.1.1.2 Exam ple 2 –Write to a Register
To set the entire CAN 0 Interrupt enables:
CAN0->CAN_INT_ENABLE |= 0x7F;
3.1.1.3
Exam ple 3 –Set and Clear Bits
To bring the CAN 0 module out of reset (set RST to 0):
CAN0->CAN_MODE &= ~MASK_CAN_MODE_RST;
To put the CAN 0 back into reset (set RST to 1):
CAN0->CAN_MODE |= MASK_CAN_MODE_RST;
190
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
3.2 API Header Files
This is a list of all the API header files. These are located in the inc directory.
ft900.h
FT900 API (all include files)
ft900_adc.h
Analogue to Digital Converter
ft900_asm.h
FT900 Assembler Macros
ft900_cam.h
Camera interface
ft900_can.h
CANBus
ft900_dac.h
Digital to Analogue Converter
ft900_delay.h
Delay functions
ft900_eth.h
Ethernet driver
ft900_gpio.h
General Purpose I/O and Pad control
ft900_i2cm.h
I2C Master
ft900_i2cs.h
I2C Slave
ft900_i2s.h
I2S Audio
ft900_interrupt.h
Interrupt management
ft900_pwm.h
Pulse Width Modulation
ft900_pwm_pcm.h
PWM Audio
ft900_rtc.h
Real Time Clock
ft900_sdhost.h
SD Host
ft900_spi.h
SPI
ft900_startup_dfu.h
Startup DFU Feature
ft900_sys.h
Chip management
ft900_timers.h
Timers
ft900_uart_simple.h
UART
ft900_usbd.h
USB Device API
ft900_usbd_dfu.h
DFU device for USB device stack API
ft900_usbh.h
USB host stack API
ft900_usbh_boms.h
BOMS devices on USB host stack API
ft900_usbh_cdcacm.h
CDC ACM devices on USB host stack API
ft900_usbh_hid.h
HID devices on USB host stack API
ft900_usbh_aoa.h
AOA devices on USB host stack API
ft900_usbhx.h
USB host API extensions
ft900_wdt.h
Watchdog Timer
191
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
3.3 Additional Header Files
This list contains all additional header files that are not directly part of the API but provide
additional definitions for the API and applications. They are located in the inc directory.
ft900_usb.h
USB definitions
ft900_usb_boms.h
USB BOMS class definitions
ft900_usb_cdc.h
USB CDC class USB definitions
ft900_usb_dfu.h
USB DFU class definitions
ft900_usb_hid.h
USB HID class definitions
ft900_usb_aoa.h
USB AOA class definitions
192
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
4 Contact Information
Head Office – Glasgow, UK
Branch Office – Tigard, Oregon, USA
Future Technology Devices International Limited
Unit 1, 2 Seaward Place, Centurion Business Park
Glasgow G41 1HH
United Kingdom
Tel: +44 (0) 141 429 2777
Fax: +44 (0) 141 429 2758
Future Technology Devices International Limited
(USA)
7130 SW Fir Loop
Tigard, OR 97223-8160
USA
Tel: +1 (503) 547 0988
Fax: +1 (503) 547 0987
E-mail (Sales)
E-mail (Support)
E-mail (General Enquiries)
[email protected]
[email protected]
[email protected]
E-Mail (Sales)
E-Mail (Support)
E-Mail (General Enquiries)
[email protected]
[email protected]
[email protected]
Branch Office – Taipei, Taiwan
Branch Office – Shanghai, China
Future Technology Devices International Limited
(Taiwan)
2F, No. 516, Sec. 1, NeiHu Road
Taipei 114
Taiwan , R.O.C.
Tel: +886 (0) 2 8791 3570
Fax: +886 (0) 2 8791 3576
Future Technology Devices International Limited
(C hina)
Room 1103, No. 666 West Huaihai Road,
Shanghai, 200052
C hina
Tel: +86 21 62351596
Fax: +86 21 62351595
E-mail (Sales)
E-mail (Support)
E-mail (General Enquiries)
E-mail (Sales)
E-mail (Support)
E-mail (General Enquiries)
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
Web Site
http://ftdichip.com
Distributor and Sales Representatives
Please visit the Sales Network page of the FTDI Web site for the contact details of our distributor(s) and sales
representative(s) in your country.
Sys tem and equipment manufacturers and des igners are responsible to ens ure that their s ystems, and any Future T ec hnology
D evic es I nternational L td (FT DI) devices inc orporated in their s ystems, meet all applicable s afety, regulatory and s ystem - level
performanc e requirements. A ll application-related information in this document (including application des c riptions , s ugges ted
FT D I devic es and other materials ) is provided for referenc e only. While FT D I has taken c are to as s ure it is ac c urate, this
information is s ubject to c ustomer c onfirmation, and FT D I dis c laims all liability for s ys tem des igns and for any applic ations
as s istance provided by FTD I. U se of FT DI devices in life s upport and/or s afety applications is entirely at the us er’s ris k, a nd the
us er agrees to defend, indemnify and hold harmles s FTDI from any and all damages , c laims , s uits or expens e res ulting from
s uc h us e. T his doc ument is s ubject to c hange without notic e. N o freedom to us e patents or other intellectual property rights is
implied by the public ation of this doc ument. N either the whole nor any part of the information c ontained in, or the produc t
des c ribed in this doc ument, may be adapted or reproduc ed in any material or electronic form without the prior written c ons ent
of the c opyright holder. Future T ec hnology D evic es I nternational L td, U nit 1 , 2 Seaward P lac e, C enturion Bus ines s P ark,
G las gow G 4 1 1 H H , U nited Kingdom. Sc otland Regis tered C ompany N umber: SC 1 3 6 6 4 0
193
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Appendix A – References
Document References
FT900/FT901/FT902/FT903 Datasheet
FT905/FT906/FT907/FT908 Datasheet
AN_325 FT900 Toolchain Installation Guide GNU Make Manual–- 9.5 Overriding Variables
(http://www.gnu.org/software/make/manual/html_node/Overriding.html#Overriding)
USB-IF Device Firmware Upgrade 1.1 Specification
http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf
USB-IF Class definitions for Communication Devices 1.2
http://www.usb.org/developers/docs/devclass_docs/CDC1.2_WMC1.1_012011.zip
USB-IF Device Class Definitions for HID 1.11
http://www.usb.org/developers/hidpage/HID1_11.pdf
USB-IF Mass Storage Bulk Only
http://www.usb.org/developers/docs/devclass_docs/usbmassbulk_10.pdf
Android Open Accessory Specification
https://source.android.com/devices/accessories/aoa2.html
Acronyms and Abbreviations
Terms
Description
ADC
Analogue to Digital Converter
AOA
Android Open Accessory
ARP
Address Resolution Protocol
CAN
Controller Area Network
DAC
Digital to Analogue Converter
EEPROM
Electronically Erasable PROgrammable Memory
GPIO
General Purpose I/O
I2C
Inter-IC
I2S
Inter-IC Sound
ICMP
Internet Control Messaging Protocol
MDI-X
Medium Dependent Interface Crossover
PC
Personal Computer
PWM
Pulse Width Modulation
194
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
RTC
Real Time Clock
SD
Secure Digital
SPI
Serial Peripheral Interface
UART
Universal Asynchronous Receiver Transmitter
WDT
Watchdog Timer
195
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Appendix B – List of Tables & Figures
List of Tables
Table 1 – FT900 Flash Geometry .............................................................................................. 180
List of Figures
Figure 1-1 FT90x Interface Driver Support .................................................................................... 6
Figure 2-1 Datalogger Partition................................................................................................. 180
Figure 2-2 D2XX Solution Context Diagram............................................................................... 182
196
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited
Application Note
AN_365 FT900 API Programmers Manual
V ers ion 1 .2
D oc ument Reference N o.: FT _001157
C learance N o.: FT DI#453
Appendix C – Revision History
Document Title:
AN_365 FT900 API Programmers Manual
Document Reference No.:
FT_001157
Clearance No.:
FTDI# 453
Product Page:
http://www.ftdichip.com/FTProducts.htm
Document Feedback:
Send Feedback
Revision
Changes
Date
1.0
Initial Release
2015-06-29
1.1
Updated to reflect changes in USB Host API
2015-09-14
1.2
Added USBH AOA API, Datalogger and D2XX API
2016-02-25
197
P roduc t Page
D oc ument Feedback
C opyright © Future T echnology D evices I nternational L imited